Running with launchd

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

Prerequisites

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

Quick Setup

1. Create the Launch Agent

Create a plist file in your LaunchAgents folder:

nano ~/Library/LaunchAgents/cloud.epochproxy.agent.plist

Paste the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>cloud.epochproxy.agent</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/epoch-agent</string>
        <string>--state-file</string>
        <string>/Users/YOUR_USERNAME/.config/epoch-agent/state.json</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/Users/YOUR_USERNAME/.config/epoch-agent/stdout.log</string>

    <key>StandardErrorPath</key>
    <string>/Users/YOUR_USERNAME/.config/epoch-agent/stderr.log</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin</string>
    </dict>
</dict>
</plist>

Important: Replace YOUR_USERNAME with your actual username.

2. Create Config Directory

mkdir -p ~/.config/epoch-agent

3. Initial Activation

If you haven’t activated the agent yet:

epoch-agent --activation-code YOUR_CODE

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

4. Load the Service

launchctl load ~/Library/LaunchAgents/cloud.epochproxy.agent.plist

5. Verify It’s Running

launchctl list | grep epochproxy

You should see cloud.epochproxy.agent with a PID.

Managing the Service

Check Status

launchctl list | grep epochproxy

A running service shows a PID number. A stopped service shows -.

Start the Service

launchctl start cloud.epochproxy.agent

Stop the Service

launchctl stop cloud.epochproxy.agent

Unload (Disable) the Service

launchctl unload ~/Library/LaunchAgents/cloud.epochproxy.agent.plist

Reload After Changes

launchctl unload ~/Library/LaunchAgents/cloud.epochproxy.agent.plist
launchctl load ~/Library/LaunchAgents/cloud.epochproxy.agent.plist

Viewing Logs

Standard Output

tail -f ~/.config/epoch-agent/stdout.log

Standard Error

tail -f ~/.config/epoch-agent/stderr.log

Both Logs

tail -f ~/.config/epoch-agent/*.log

System-Wide Installation

To run the agent for all users (requires admin privileges):

1. Create System Plist

sudo nano /Library/LaunchDaemons/cloud.epochproxy.agent.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>cloud.epochproxy.agent</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/epoch-agent</string>
        <string>--state-file</string>
        <string>/var/lib/epoch-agent/state.json</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/var/log/epoch-agent.log</string>

    <key>StandardErrorPath</key>
    <string>/var/log/epoch-agent.error.log</string>
</dict>
</plist>

2. Create State Directory

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

3. Load as Daemon

sudo launchctl load /Library/LaunchDaemons/cloud.epochproxy.agent.plist

Troubleshooting

Service Won’t Start

Check the error log:

cat ~/.config/epoch-agent/stderr.log

“Operation not permitted”

The binary may be quarantined. Remove the quarantine attribute:

xattr -d com.apple.quarantine /usr/local/bin/epoch-agent

Service Keeps Restarting

Check for:

1. Valid state file exists
2. Network connectivity
3. Correct file paths in the plist

Wrong ProgramArguments Path

Verify the agent binary location:

which epoch-agent

Update the plist if the path is different.