/

Server Agent - Linux & macOS

Install the ByteHide Server Agent on Linux or macOS for zero-code runtime protection of all .NET applications. Install once, and every .NET 6+ process on the machine is automatically protected.

Requirements

  • Linux (x64, ARM64, Alpine) or macOS (x64, Apple Silicon)
  • .NET 6+ runtime installed (for the apps you want to protect)
  • curl or wget
  • sudo access (for writing to /opt/ and /etc/)
  • A ByteHide account with a Monitor project (create one here)
  • Your ByteHide Project Token from app.bytehide.com

No .NET SDK required. Downloads a self-contained binary from GitHub.

Bash
curl -sSL https://raw.githubusercontent.com/bytehide/monitor-dotnet-agent/main/install.sh | bash -s -- --token bh_xxxxxxxxxxxx

This single command:

  1. Detects your OS and architecture automatically
  2. Downloads the correct binary from GitHub Releases
  3. Extracts agent DLLs to the install directory
  4. Configures environment variables system-wide
  5. Installs bytehide-agent to /usr/local/bin/

Script Options

OptionDefaultDescription
--token, -t(required)Your ByteHide API token
--version1.0.5Agent version to install
--install-dir/usr/local/binWhere to place the CLI binary
--no-installfalseOnly download binary, don't run install

Private Hosting

If you host the binary on a private server:

Bash
BYTEHIDE_AGENT_URL=https://your-server.com/bytehide-agent-1.0.5-linux-x64.tar.gz \
  curl -sSL https://raw.githubusercontent.com/bytehide/monitor-dotnet-agent/main/install.sh | bash -s -- --token bh_xxxxxxxxxxxx

Option 2: dotnet tool

Requires the .NET SDK installed on the server.

Bash
# Install the CLI tool
dotnet tool install -g Bytehide.Monitor.AgentCli

# Run the agent installer
bytehide-agent install --token bh_xxxxxxxxxxxx

If using a private NuGet feed:

Bash
dotnet nuget add source "https://pkgs.dev.azure.com/bytehide/Monitor/_packaging/bytehide-monitor-enterprise/nuget/v3/index.json" \
    --name bytehide --username bytehide --password "YOUR_PAT" --store-password-in-clear-text

dotnet tool install -g Bytehide.Monitor.AgentCli --version 1.0.5
bytehide-agent install --token bh_xxxxxxxxxxxx

What Gets Installed

Linux

ItemPath
Agent DLLs/opt/bytehide/agent/
CLI binary/usr/local/bin/bytehide-agent
Configuration/opt/bytehide/agent/monitor.config.json
Logs/opt/bytehide/agent/logs/

macOS

ItemPath
Agent DLLs/usr/local/share/bytehide/agent/
CLI binary/usr/local/bin/bytehide-agent
Configuration/usr/local/share/bytehide/agent/monitor.config.json
Logs/usr/local/share/bytehide/agent/logs/

Environment Variables

The installer configures environment variables in multiple locations to cover all scenarios:

Linux:

FilePurpose
/etc/profile.d/bytehide-agent.shInteractive shell sessions (SSH, bash)
/etc/environment.d/bytehide-agent.confsystemd services
/etc/environmentUniversal fallback

macOS:

FilePurpose
/etc/zshenvAll zsh sessions (default shell on macOS)
launchctl setenvImmediate effect in current session

Variables Set

VariableValue (Linux)
DOTNET_STARTUP_HOOKS/opt/bytehide/agent/Bytehide.Monitor.ServerAgent.dll
ASPNETCORE_HOSTINGSTARTUPASSEMBLIESBytehide.Monitor.ServerAgent
BYTEHIDE_MONITOR_TOKENYour token
BYTEHIDE_MONITOR_CONFIG/opt/bytehide/agent/monitor.config.json

Verify Installation

Bash
bytehide-agent status

Expected output:

CODE
  Installed:     Yes
  Install path:  /opt/bytehide/agent
  Agent files:   7 DLLs

  Environment Variables:
    DOTNET_STARTUP_HOOKS = /opt/bytehide/agent/Bytehide.Monitor.ServerAgent.dll
    ASPNETCORE_HOSTINGSTARTUPASSEMBLIES = Bytehide.Monitor.ServerAgent
    BYTEHIDE_MONITOR_TOKEN = bh_xxx...xxxx

  Protection:    Active — all new .NET processes are protected

Restart Required

After installing the agent, you must restart any running .NET applications for protection to take effect. Existing processes do not pick up environment variable changes automatically.

Platform-Specific Notes

systemd Services

For .NET apps running as systemd services, the agent environment is loaded automatically from /etc/environment.d/bytehide-agent.conf. No changes to your service files needed.

If you want to set variables per-service instead of system-wide:

INI
[Service]
Environment=DOTNET_STARTUP_HOOKS=/opt/bytehide/agent/Bytehide.Monitor.ServerAgent.dll
Environment=ASPNETCORE_HOSTINGSTARTUPASSEMBLIES=Bytehide.Monitor.ServerAgent
Environment=BYTEHIDE_MONITOR_TOKEN=bh_xxxxxxxxxxxx

Alpine Linux (musl)

The installer automatically detects Alpine/musl and downloads the linux-musl-x64 binary. No extra configuration needed.

SSH Sessions

After installing, new SSH sessions automatically pick up the environment variables from /etc/profile.d/bytehide-agent.sh. For the current session:

Bash
source /etc/profile.d/bytehide-agent.sh

Supported Platforms

PlatformArchitectureRID
Linux (glibc)x64linux-x64
Linux (glibc)ARM64linux-arm64
Linux (musl/Alpine)x64linux-musl-x64
macOSIntelosx-x64
macOSApple Siliconosx-arm64

Troubleshooting

Agent not loading

  1. Check that environment variables are set:

    Bash
    echo $DOTNET_STARTUP_HOOKS

    If empty, source the profile:

    Bash
    source /etc/profile.d/bytehide-agent.sh

  2. Verify the DLL exists:

    Bash
    ls -la /opt/bytehide/agent/Bytehide.Monitor.ServerAgent.dll

  3. Make sure you restarted the application after installing the agent.

Permission errors

Run with sudo:

Bash
curl -sSL https://raw.githubusercontent.com/bytehide/monitor-dotnet-agent/main/install.sh | sudo bash -s -- --token bh_xxxxxxxxxxxx

systemd service not picking up variables

Reload systemd after install:

Bash
sudo systemctl daemon-reload
sudo systemctl restart your-app.service

Next Steps

Previous
Windows
Next
Docker