Agent Installation & Setup

1. Download

Download the latest eg-agent binary from GitHub Releases, or use the Docker image for containerized deployments.

Linux

# Linux amd64
curl -LO https://github.com/entropy8-io/entryguard-io-cli/releases/latest/download/eg-agent_linux_amd64.tar.gz
tar xzf eg-agent_linux_amd64.tar.gz

# Linux arm64
curl -LO https://github.com/entropy8-io/entryguard-io-cli/releases/latest/download/eg-agent_linux_arm64.tar.gz
tar xzf eg-agent_linux_arm64.tar.gz

Move it to a system path:

sudo mv eg-agent /usr/local/bin/
sudo chmod +x /usr/local/bin/eg-agent

Windows

Download the zip for your architecture:

• eg-agent_windows_amd64.zip
• eg-agent_windows_arm64.zip

Extract eg-agent.exe to C:\eg-agent\:

# Run in an elevated PowerShell prompt
New-Item -ItemType Directory -Force -Path C:\eg-agent
Expand-Archive eg-agent_windows_amd64.zip -DestinationPath C:\eg-agent

Optionally, add C:\eg-agent to your system PATH.

2. Create an API Key

In the EntryGuard dashboard:

1. Go to Settings → API Keys
2. Click Create API Key
3. Select the agent:connect scope
4. Copy the key — you'll need it in the next step

3. Create Script Directories

Each resource the agent manages needs a script directory with apply/ and revoke/ subdirectories containing your numbered scripts.

Linux:

sudo mkdir -p /etc/eg-agent/scripts/my-resource/{apply,revoke}

Windows (elevated PowerShell):

New-Item -ItemType Directory -Force -Path C:\eg-agent\scripts\my-resource\apply
New-Item -ItemType Directory -Force -Path C:\eg-agent\scripts\my-resource\revoke

The agent calls your scripts with two arguments:

Argument	Description	Example
$1 / $args[0]	CIDR to apply/revoke	203.0.113.50/32
$2 / $args[1]	Description (session info)	EntryGuard session abc-123

Exit code 0 = success. Any other exit code = failure. Stdout and stderr are captured and reported back to EntryGuard.

Scripts must follow the NN- naming convention (e.g., 01-ufw.sh, 02-traefik.sh). See Script Directories → for details and Example Scripts → for ready-to-use templates.

4. Initialize

Run the interactive setup:

Linux:

sudo eg-agent init

Windows (elevated PowerShell):

C:\eg-agent\eg-agent.exe init

This prompts for:

• Server URL — defaults to https://app.entryguard.io/api/v1
• API Key — your agent:connect key
• Agent name — defaults to hostname, must be unique per organization

The setup tests the connection, registers the agent with EntryGuard, and writes the config file.

• Linux: /etc/eg-agent/config.yml
• Windows: C:\eg-agent\config.yml

5. Run

Start the agent:

Linux:

sudo eg-agent run

Windows (elevated PowerShell):

C:\eg-agent\eg-agent.exe run

The agent will:

1. Register with EntryGuard (or re-register if already registered)
2. Start sending heartbeats every 30 seconds
3. Poll for commands every 3 seconds
4. Execute scripts from the resource's script directory when commands arrive

6. Run as a Service

Linux (systemd)

For production use, create a systemd unit:

sudo tee /etc/systemd/system/eg-agent.service > /dev/null <<'EOF'
[Unit]
Description=EntryGuard Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/eg-agent run
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable eg-agent
sudo systemctl start eg-agent

Check status:

sudo systemctl status eg-agent
sudo journalctl -u eg-agent -f

Windows Service

The recommended way to run eg-agent as a Windows Service is with NSSM (Non-Sucking Service Manager):

# Install NSSM (or download from https://nssm.cc/download)
# Then install the service:
nssm install eg-agent C:\eg-agent\eg-agent.exe run
nssm set eg-agent AppDirectory C:\eg-agent
nssm set eg-agent Description "EntryGuard Agent"
nssm set eg-agent Start SERVICE_AUTO_START

# Start the service
nssm start eg-agent

Alternatively, use sc.exe directly:

sc.exe create eg-agent binPath= "C:\eg-agent\eg-agent.exe run" start= auto
sc.exe start eg-agent

Check status:

nssm status eg-agent
# or
Get-Service eg-agent

7. Create a Resource in EntryGuard

After the agent is registered, create a credential and resource in the dashboard:

1. Create credential: Provider = AGENT, credential data = {"agentId": "<agent-id>"} (the agent ID is shown during eg-agent init)
2. Create resource: Use the AGENT credential, set a descriptive resource identifier (e.g., prod-nginx-01), resource type = Script
3. Set Script Directory: Enter the path to the script directory on the agent host (e.g., /etc/eg-agent/scripts/my-resource)
4. Assign to a role: Add the resource to a role so users can start sessions against it

Configuration Reference

Linux

Config file at /etc/eg-agent/config.yml:

server:
  url: "https://app.entryguard.io/api/v1"
  api_key: "eg_..."

agent:
  name: "prod-nginx-01"
  poll_interval: 3s        # How often to check for commands
  heartbeat_interval: 30s  # How often to report status

execution:
  timeout: 30s             # Default max time per script (overridden by resource's Script Timeout)
  shell: "/bin/bash"       # Shell used to execute scripts

# Optional: enable tunnel mode (see Secure Tunnels docs)
tunnel:
  enabled: false
  edge_url: "wss://edge.entryguard.io"

Script directories are configured per-resource

The agent config does not contain script paths. Each resource's Script Directory is configured in the EntryGuard dashboard and sent to the agent with each command. This means one agent can serve multiple resources, each with different scripts.

Windows

Config file at C:\eg-agent\config.yml:

server:
  url: "https://app.entryguard.io/api/v1"
  api_key: "eg_..."

agent:
  name: "prod-iis-01"
  poll_interval: 3s
  heartbeat_interval: 30s

execution:
  timeout: 30s
  shell: "powershell.exe"  # Or "pwsh.exe" for PowerShell 7+

# Optional: enable tunnel mode (see Secure Tunnels docs)
tunnel:
  enabled: false
  edge_url: "wss://edge.entryguard.io"

Docker & Kubernetes

The agent is also available as a multi-arch Docker image:

docker pull ghcr.io/entropy8-io/eg-agent:latest

For full deployment guides with Docker Compose and Kubernetes manifests, see Docker & Kubernetes →.

Check Status

eg-agent status

Shows config, tests the connection, and displays the agent's current state on the server.