Configuration File

The agent can be configured using a TOML file. By default, it looks for config/agent.toml, but you can specify a different path with --config.

File Location

# Use default location
epoch-agent

# Use custom config file
epoch-agent --config /etc/epoch-agent/config.toml

Complete Example

# EpochProxy Agent Configuration

[api]
# API server URL for activation and management
url = "https://api.epochproxy.cloud"

[agent]
# Activation code (required for first-time setup)
# Can also be provided via --activation-code or EPOCH_ACTIVATION_CODE
activation_code = "YOUR_ACTIVATION_CODE"

# Optional: Agent name (for display in dashboard)
name = "production-server-1"

# Optional: Labels for organizing agents
[agent.labels]
environment = "production"
region = "us-east-1"
team = "backend"

[shell]
# Shell executable path
path = "/bin/bash"

[reconnect]
# Reconnection settings (optional)
initial_delay_ms = 1000
max_delay_ms = 60000
max_retries = 0  # 0 = infinite retries

Configuration Sections

[api]

Configure the connection to the EpochProxy API server.

Key	Type	Default	Description
url	string	https://api.epochproxy.cloud	API server URL

[agent]

Agent identification and registration settings.

Key	Type	Default	Description
activation_code	string	-	Activation code (required for first setup)
name	string	hostname	Display name in dashboard
labels	table	{}	Key-value labels for organization

[shell]

Terminal session configuration.

Key	Type	Default	Description
path	string	/bin/bash	Shell executable

[reconnect]

Automatic reconnection behavior.

Key	Type	Default	Description
initial_delay_ms	integer	1000	Initial reconnect delay
max_delay_ms	integer	60000	Maximum reconnect delay
max_retries	integer	0	Max retry attempts (0 = infinite)

Minimal Configuration

For most use cases, you only need the activation code:

[agent]
activation_code = "YOUR_CODE"

All other settings use sensible defaults.

Systemd Service Configuration

When running as a systemd service, place the config at /etc/epoch-agent/config.toml:

sudo mkdir -p /etc/epoch-agent
sudo nano /etc/epoch-agent/config.toml

Then reference it in your service file:

ExecStart=/usr/local/bin/epoch-agent --config /etc/epoch-agent/config.toml

Configuration Precedence

1. Default values (built into the binary)
2. Configuration file values
3. Environment variables (EPOCH_*)
4. Command-line arguments (--*)

Command-line arguments always take precedence.