Skip to content
EpochProxy Docs

Environment Variables

Environment variables provide a convenient way to configure the agent, especially in containerized environments.

Agent Configuration

Section titled “Agent Configuration”

EPOCH_ACTIVATION_CODE

Section titled “EPOCH_ACTIVATION_CODE”

The activation code for first-time agent registration.

Terminal window
export EPOCH_ACTIVATION_CODE=ABC123XYZ
epoch-agent

EPOCH_STATE_FILE

Section titled “EPOCH_STATE_FILE”

Path to store the agent’s persisted state (ID and auth token).

Terminal window
export EPOCH_STATE_FILE=/var/lib/epoch-agent/state.json
epoch-agent

Default locations:

  • Linux/macOS: ~/.config/epoch-agent/state.json
  • Windows: %PROGRAMDATA%\epoch-agent\state.json

EPOCH_API_ADDR

Section titled “EPOCH_API_ADDR”

Address of the EpochProxy API server.

Terminal window
export EPOCH_API_ADDR=https://api.epochproxy.cloud
epoch-agent

Logging Configuration

Section titled “Logging Configuration”

RUST_LOG

Section titled “RUST_LOG”

Controls log verbosity using the standard Rust logging format.

Terminal window
# Debug logging for the agent
export RUST_LOG=epoch_agent=debug
epoch-agent


# Trace logging (very verbose)
export RUST_LOG=epoch_agent=trace
epoch-agent


# Info level for everything
export RUST_LOG=info
epoch-agent


# Multiple directives
export RUST_LOG=info,epoch_agent=debug,hyper=warn
epoch-agent

Log levels (least to most verbose):

  • error - Only errors
  • warn - Warnings and errors
  • info - General information (default)
  • debug - Debug information
  • trace - Very detailed tracing

System Environment Variables

Section titled “System Environment Variables”

The agent also respects these standard environment variables:

HOME

Section titled “HOME”

Used to determine the default state file location on Unix systems.

XDG_CONFIG_HOME

Section titled “XDG_CONFIG_HOME”

If set, the agent stores its state file in $XDG_CONFIG_HOME/epoch-agent/state.json instead of ~/.config/epoch-agent/state.json.

SHELL

Section titled “SHELL”

The default shell on Unix systems. The agent uses this if --shell is not specified.

COMSPEC

Section titled “COMSPEC”

The default command interpreter on Windows. The agent uses this if --shell is not specified.

Docker Example

Section titled “Docker Example”
FROM debian:bookworm-slim


COPY epoch-agent /usr/local/bin/


ENV EPOCH_API_ADDR=https://api.epochproxy.cloud
ENV EPOCH_STATE_FILE=/var/lib/epoch-agent/state.json
ENV RUST_LOG=info


ENTRYPOINT ["epoch-agent"]
Terminal window
docker run -e EPOCH_ACTIVATION_CODE=ABC123XYZ \
           -v epoch-state:/var/lib/epoch-agent \
           epoch-agent

Precedence

Section titled “Precedence”

Configuration values are applied in this order (later overrides earlier):

  1. Default values
  2. Configuration file (--config)
  3. Environment variables
  4. Command-line arguments

For example, --activation-code on the command line overrides EPOCH_ACTIVATION_CODE.