/

Agent CLI Reference

The bytehide-agent CLI manages the ByteHide Server Agent. Use it to install, configure, monitor, and uninstall the agent.

Commands

CommandDescription
bytehide-agent installInstall the agent and configure protection
bytehide-agent uninstallRemove the agent completely
bytehide-agent statusShow current agent status
bytehide-agent configView or modify configuration
bytehide-agent logsView agent logs
bytehide-agent --versionShow version
bytehide-agent --helpShow help

install

Installs the agent DLLs, sets environment variables, and writes the default configuration.

Bash
bytehide-agent install --token <your-token> [--force]
OptionDescription
--token, -t(required) Your ByteHide API token
--force, -fReinstall even if already installed

What it does

  1. Extracts agent DLLs to the install directory
  2. Creates the log directory
  3. Sets system-wide environment variables (DOTNET_STARTUP_HOOKS, ASPNETCORE_HOSTINGSTARTUPASSEMBLIES, BYTEHIDE_MONITOR_TOKEN, BYTEHIDE_MONITOR_CONFIG)
  4. Writes monitor.config.json with default settings

Example

Bash
$ sudo bytehide-agent install --token bh_LYkAhiIrlXQMHALfU8NDILAKx0K9oDcPQ

  ── Installing ByteHide Server Agent ──

  [1/4] Extracting agent files... OK (7 files)
  [2/4] Creating directories... OK
  [3/4] Configuring environment... OK
  [4/4] Writing configuration... OK

  ✓ ByteHide Server Agent installed successfully!

  Install path:  /opt/bytehide/agent
  Hook DLL:      /opt/bytehide/agent/Bytehide.Monitor.ServerAgent.dll
  Config:        /opt/bytehide/agent/monitor.config.json
  Logs:          /opt/bytehide/agent/logs

  IMPORTANT: Restart any running .NET applications for protection to take effect.

uninstall

Removes the agent completely: deletes DLLs, removes environment variables, and cleans up configuration files.

Bash
bytehide-agent uninstall [--yes]
OptionDescription
--yes, -ySkip confirmation prompt

Example

Bash
$ sudo bytehide-agent uninstall

  ── Uninstalling ByteHide Server Agent ──

  Are you sure you want to uninstall? This will remove all protection. [y/N] y
  [1/2] Removing environment variables... OK
  [2/2] Removing agent files... OK

  ✓ ByteHide Server Agent uninstalled.
  Running applications will continue to be protected until they are restarted.

status

Shows the current installation state, environment variables, and protection status.

Bash
bytehide-agent status

Example

Bash
$ bytehide-agent status

  ── ByteHide Server Agent Status ──

  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_LYk...oDcPQ

  Protection:    Active — all new .NET processes are protected

  Config file:   /opt/bytehide/agent/monitor.config.json
  Log files:     2 file(s) in /opt/bytehide/agent/logs

Status Indicators

StatusMeaning
ActiveAgent is installed and environment variables are configured correctly
InactiveAgent files exist but environment variables are missing or incorrect
DisabledAgent is installed but BYTEHIDE_DISABLE=true is set
Not installedNo agent files found

config

View or modify agent configuration.

Show configuration

Bash
bytehide-agent config show

Displays the contents of monitor.config.json:

JSON
{
  "token": "bh_LYkAhiIrlXQMHALfU8NDILAKx0K9oDcPQ",
  "logging": {
    "console": true,
    "level": "info",
    "file": {
      "enabled": true,
      "path": "/opt/bytehide/agent/logs/monitor.log",
      "maxSizeMB": 50
    }
  }
}

Set a configuration value

Bash
bytehide-agent config set <key> <value>
KeyDescriptionExample
tokenUpdate your ByteHide API tokenbytehide-agent config set token bh_newtoken
debugEnable/disable debug loggingbytehide-agent config set debug true
disabledDisable agent without uninstallingbytehide-agent config set disabled true

Examples

Change token:

Bash
$ bytehide-agent config set token bh_newtoken123
  Token updated. Restart .NET applications for changes to take effect.

Enable debug mode:

Bash
$ bytehide-agent config set debug true
  Debug mode set to: true

Temporarily disable protection:

Bash
$ bytehide-agent config set disabled true
  Agent disabled. New .NET processes will NOT be protected.

Re-enable protection:

Bash
$ bytehide-agent config set disabled false
  Agent enabled. New .NET processes will be protected.

logs

View agent logs from protected applications.

Bash
bytehide-agent logs [--follow] [--lines <n>]
OptionDefaultDescription
--follow, -ffalseFollow log output in real-time (like tail -f)
--lines, -n50Number of lines to show

Examples

Show last 50 lines:

Bash
bytehide-agent logs

Show last 100 lines:

Bash
bytehide-agent logs --lines 100

Follow logs in real-time:

Bash
bytehide-agent logs --follow

Install Paths

PlatformAgent DLLsCLI Binary
Linux/opt/bytehide/agent//usr/local/bin/bytehide-agent
macOS/usr/local/share/bytehide/agent//usr/local/bin/bytehide-agent
WindowsC:\Program Files\ByteHide\Agent\C:\Program Files\ByteHide\CLI\bytehide-agent.exe

Environment Variables

These are the environment variables managed by the agent:

VariableDescription
DOTNET_STARTUP_HOOKSPath to the startup hook DLL. Set by install, removed by uninstall.
ASPNETCORE_HOSTINGSTARTUPASSEMBLIESAssembly name for ASP.NET Core hosting startup.
BYTEHIDE_MONITOR_TOKENYour ByteHide API token. Changed via config set token.
BYTEHIDE_MONITOR_CONFIGPath to monitor.config.json.
BYTEHIDE_DISABLESet to true to disable protection. Changed via config set disabled.
BYTEHIDE_DEBUGSet to true for verbose debug output. Changed via config set debug.

Common Workflows

Update token on a running server

Bash
bytehide-agent config set token bh_newtoken
# Then restart your apps
sudo systemctl restart myapp

Temporarily disable protection for debugging

Bash
bytehide-agent config set disabled true
# Restart your app without protection
sudo systemctl restart myapp

# Re-enable when done
bytehide-agent config set disabled false
sudo systemctl restart myapp

Check if agent is working

Bash
# 1. Check install status
bytehide-agent status

# 2. Enable debug mode
bytehide-agent config set debug true

# 3. Restart your app and check logs
sudo systemctl restart myapp
bytehide-agent logs --follow

# 4. Look for: [ByteHide Server Agent] Initialized (PID: xxxxx)

Next Steps

Previous
Docker
Next
Cloud Configuration