Running with systemd

Running the agent as a systemd service ensures it starts automatically on boot and restarts if it crashes.

Prerequisites

• Linux system with systemd
• EpochProxy agent installed to /usr/local/bin/epoch-agent
• Agent already activated (has valid state file)

Quick Setup

1. Create the Service File

sudo nano /etc/systemd/system/epoch-agent.service

Paste the following:

[Unit]
Description=EpochProxy Agent
Documentation=https://docs.epochproxy.cloud
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/epoch-agent --state-file /var/lib/epoch-agent/state.json
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

# Security hardening (optional but recommended)
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/var/lib/epoch-agent

[Install]
WantedBy=multi-user.target

2. Create State Directory

sudo mkdir -p /var/lib/epoch-agent

3. Initial Activation

If you haven’t activated the agent yet, run it manually first:

sudo epoch-agent --activation-code YOUR_CODE --state-file /var/lib/epoch-agent/state.json

Press Ctrl+C after you see “Agent is ready”.

4. Enable and Start the Service

# Reload systemd to recognize the new service
sudo systemctl daemon-reload

# Enable the service to start on boot
sudo systemctl enable epoch-agent

# Start the service now
sudo systemctl start epoch-agent

5. Verify It’s Running

sudo systemctl status epoch-agent

You should see “active (running)”.

Managing the Service

View Status

sudo systemctl status epoch-agent

Start/Stop/Restart

sudo systemctl start epoch-agent
sudo systemctl stop epoch-agent
sudo systemctl restart epoch-agent

View Logs

# Recent logs
sudo journalctl -u epoch-agent -n 50

# Follow logs in real-time
sudo journalctl -u epoch-agent -f

# Logs since boot
sudo journalctl -u epoch-agent -b

Disable Auto-Start

sudo systemctl disable epoch-agent

Running as Non-Root User

For additional security, run the agent as a dedicated user:

1. Create the User

sudo useradd --system --no-create-home --shell /usr/sbin/nologin epoch-agent

2. Set Up Directories

sudo mkdir -p /var/lib/epoch-agent
sudo chown epoch-agent:epoch-agent /var/lib/epoch-agent

3. Update the Service File

Change the User line:

[Service]
User=epoch-agent
Group=epoch-agent

4. Reload and Restart

sudo systemctl daemon-reload
sudo systemctl restart epoch-agent

Configuration with Config File

Instead of command-line arguments, use a config file:

1. Create Config Directory

sudo mkdir -p /etc/epoch-agent

2. Create Config File

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

[api]
url = "https://api.epochproxy.cloud"

[shell]
path = "/bin/bash"

3. Update Service File

ExecStart=/usr/local/bin/epoch-agent --config /etc/epoch-agent/config.toml --state-file /var/lib/epoch-agent/state.json

Troubleshooting

Service Won’t Start

Check the logs:

sudo journalctl -u epoch-agent -n 100 --no-pager

Permission Denied Errors

Ensure the state directory is writable:

sudo chown -R epoch-agent:epoch-agent /var/lib/epoch-agent

Service Keeps Restarting

The agent may be failing to connect. Check:

1. Network connectivity to api.epochproxy.cloud
2. Valid activation code or state file
3. Firewall rules allowing outbound connections