Agent Installation & Setup

1. Download

Download the latest eg-agent binary from GitHub Releases:

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. Write Your Scripts

Create script directories and your apply/revoke scripts.

Linux:

sudo mkdir -p /etc/eg-agent/scripts

Windows (elevated PowerShell):

New-Item -ItemType Directory -Force -Path C:\eg-agent\scripts

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.

See 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
• Script paths — paths to your apply and revoke scripts

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 your scripts 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 = linux_host
3. 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

scripts:
  apply: "/etc/eg-agent/scripts/apply.sh"
  revoke: "/etc/eg-agent/scripts/revoke.sh"

execution:
  timeout: 30s             # Max time a script can run
  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"

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

scripts:
  apply: "C:\\eg-agent\\scripts\\apply.ps1"
  revoke: "C:\\eg-agent\\scripts\\revoke.ps1"

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"

Check Status

eg-agent status

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