CLI Reference
Synopsis
Section titled “Synopsis”epoch-agent [OPTIONS]Options
Section titled “Options”--activation-code <CODE>
Section titled “--activation-code <CODE>”Required for first-time setup
The activation code from your EpochProxy dashboard. Can also be set via the EPOCH_ACTIVATION_CODE environment variable or in the config file.
epoch-agent --activation-code ABC123XYZ--config, -c <PATH>
Section titled “--config, -c <PATH>”Path to the configuration file.
- Default:
config/agent.toml - Example:
epoch-agent -c /etc/epoch-agent/config.toml
--state-file <PATH>
Section titled “--state-file <PATH>”Path to store persisted agent credentials after activation. The agent saves its ID and authentication token here for automatic reconnection.
- Default (Linux):
~/.config/epoch-agent/state.json - Default (macOS):
~/.config/epoch-agent/state.json - Default (Windows):
%PROGRAMDATA%\epoch-agent\state.json - Environment variable:
EPOCH_STATE_FILE
epoch-agent --state-file /var/lib/epoch-agent/state.json--api-addr <URL>
Section titled “--api-addr <URL>”Address of the EpochProxy API server.
- Default:
https://api.epochproxy.cloud - Environment variable:
EPOCH_API_ADDR
epoch-agent --api-addr https://api.example.com:50051--shell <PATH>
Section titled “--shell <PATH>”Shell executable to use for terminal sessions.
- Default (Linux/macOS):
/bin/bash - Default (Windows):
cmd.exe
epoch-agent --shell /bin/zsh--max-sessions <NUMBER>
Section titled “--max-sessions <NUMBER>”Maximum number of concurrent terminal sessions allowed.
- Default:
10
epoch-agent --max-sessions 5--force-activate
Section titled “--force-activate”Force re-activation, ignoring any saved state file. Use this if you need to re-register the agent with a new activation code.
epoch-agent --force-activate --activation-code NEW_CODE--help, -h
Section titled “--help, -h”Display help information.
epoch-agent --help--version, -V
Section titled “--version, -V”Display version information.
epoch-agent --versionExamples
Section titled “Examples”Basic Activation
Section titled “Basic Activation”epoch-agent --activation-code ABC123XYZCustom Configuration
Section titled “Custom Configuration”epoch-agent \ --config /etc/epoch-agent/config.toml \ --state-file /var/lib/epoch-agent/state.json \ --shell /bin/zsh \ --max-sessions 20Using Environment Variables
Section titled “Using Environment Variables”export EPOCH_ACTIVATION_CODE=ABC123XYZexport EPOCH_STATE_FILE=/var/lib/epoch-agent/state.jsonepoch-agentRe-activate with New Code
Section titled “Re-activate with New Code”epoch-agent --force-activate --activation-code NEW_CODEExit Codes
Section titled “Exit Codes”| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Configuration error |
| 3 | Connection error |