Skip to main content

EntryGuard Agent (eg-agent)

The EntryGuard Agent is a lightweight daemon that runs on Linux and Windows machines. It has two capabilities:

  • Script mode — Applies IP whitelisting rules by executing your own scripts. Covers use cases where there's no cloud API — on-prem servers, VPS instances, self-hosted services.
  • Tunnel mode — Creates secure TCP tunnels to services in private networks (databases, APIs, internal tools). No VPN, no public IPs needed.

How It Works​

┌──────────────┐         ┌──────────────────┐         ┌───────────────────┐
│  EntryGuard  │◄───────►│    eg-agent       │────────►│  Your Scripts     │
│  Server      │  polls  │    (daemon)       │  runs   │  apply.sh/.ps1    │
│              │         │                   │         │  revoke.sh/.ps1   │
└──────────────┘         └──────────────────┘         └───────────────────┘
  1. A user starts a session in EntryGuard (web or CLI)
  2. EntryGuard creates a command: "apply 203.0.113.50/32"
  3. The agent polls for commands every few seconds
  4. The agent executes your apply script with the CIDR as an argument
  5. When the session expires, the agent executes your revoke script
You control the scripts

The agent never generates or runs arbitrary commands. It only calls the scripts you've written and configured. EntryGuard passes the CIDR — your script decides what to do with it: add an iptables rule, update UFW, modify an nginx allowlist, add a Windows Firewall rule, call a Traefik API, or anything else.

Why Use the Agent?​

  • No inbound access needed — The agent polls outbound. No firewall holes, no public endpoints, no port forwarding.
  • Any service — iptables, ufw, nginx, Windows Firewall, Traefik, HAProxy, WireGuard, custom applications — anything you can script.
  • You own the logic — Scripts are plain shell or PowerShell scripts on your machine. You write them, you control them, you audit them.
  • Automatic cleanup — When sessions expire, revoke scripts run automatically.
  • FIFO execution — When multiple users start sessions, commands are queued and executed in order. No race conditions.
  • Lightweight — Single static binary, ~12MB, no runtime dependencies.

Security Model​

The agent follows a strict contract:

What the agent doesWhat the agent does NOT do
Polls EntryGuard for pending commandsGenerate or interpret firewall rules
Passes CIDR and description to your scriptsExecute anything not in your configured scripts
Reports script exit codes and output backModify system configuration directly
Sends heartbeats to report its statusAccept inbound connections

Your scripts are the single source of truth for what happens on the machine. The agent is a delivery mechanism — it brings the CIDR to your script and reports the result.

Prerequisites​

  • A Linux or Windows machine (amd64 or arm64)
  • An EntryGuard account on the Starter plan or above
  • An API key with the agent:connect scope
  • Apply and revoke scripts (see Example Scripts)

Next Steps​