Agent Gateway (TCP Relay)

The Athena Agent Gateway is a small, standalone TCP passthrough relay you run on a host inside a customer network. Hermes agents on that network connect to the gateway, and the gateway forwards their traffic to an upstream Athena agent channel. Only the gateway host needs egress to the upstream server, and TLS stays end to end between each agent and Athena the whole way — the gateway copies encrypted bytes and holds no agent credentials.

When to use a gateway#

A managed agent normally makes a single outbound connection to the Athena server's agent channel (TCP 8444 by default; see Network Ports & Firewall). In some networks you don't want every agent host to have that egress. The gateway gives you a middle hop:

• You have a segment full of agents but want one host — not every host — to hold the route out to the upstream Athena server.
• You are relaying across a private overlay (for example a LAN or Tailscale address) into a cloud-hosted Athena server, and want the crossing point to be explicit and monitored.
• You want a chokepoint you can firewall, meter, and health-check independently of both the agents and the server.

Pointing agents at the gateway is a DNS change, not a protocol change. Agents keep the Athena hostname, so their TLS hostname verification still holds; you simply make that hostname resolve to the gateway on the agent network. Because TLS is not terminated at the gateway, the relay never sees agent identities or report contents — it cannot decrypt, inspect, or alter the traffic it carries.

How it works#

One gateway instance forwards to exactly one configured upstream destination. There is deliberately no request-supplied destination — a relay that could be told where to connect would be an open proxy. For each incoming agent connection the gateway opens a fresh socket to the upstream and copies bytes through unchanged in both directions.

• Bind: the gateway listens on a specific interface address you configure (never a wildcard by default), on its listen port.
• Forward: the upstream host is resolved fresh per connection, so a change to the upstream address is picked up without restarting the relay.
• Cap: a hard ceiling on established connections protects the host; connections beyond the ceiling are refused immediately while existing sessions keep running.
• Drain: on shutdown the gateway stops accepting new connections first, then lets in-flight streams finish for a configurable drain window before cutting anything.

Configuration#

All settings live under a Gateway section in the gateway's appsettings.json, alongside the binary. Every key can also be supplied as an environment variable using the standard double-underscore form, e.g. Gateway__ListenAddress and Gateway__UpstreamHost — convenient for containers and secret injection.

A minimal appsettings.json for a gateway on a LAN address forwarding to a cloud server:

{
  "Gateway": {
    "ListenAddress": "10.20.0.5",
    "ListenPort": 8444,
    "UpstreamHost": "203.0.113.10",
    "UpstreamPort": 8444
  }
}

Validating the configuration#

The gateway validates its whole configuration before it binds a listener, so a bad config is a clean startup failure that names every problem at once rather than a runtime surprise. You can run that check on demand without starting the relay:

# Check a config change before restarting a live gateway
Athena.Gateway --validate

On success it prints the resolved listen and upstream endpoints and exits 0. On a bad config it prints each problem on its own line and exits 78 (EX_CONFIG), which makes it easy to gate deployments in CI or in a service's pre-start step. Common messages you may see:

• ListenAddress is required — set it to the interface agents reach the gateway on, not a wildcard.
• UpstreamHost is required — the single destination to forward to, resolved outside the DNS override.
• ListenPort/UpstreamPort/HealthPort must be between 1 and 65535.
• HealthPort collides with ListenPort — the health surface must not share the port agents relay through.
• UpstreamHost:UpstreamPort points at this gateway's own listener — the self-route guard.

Deploying the gateway#

The gateway runs equally as a Linux systemd service, a container, or a Windows service. It needs no privileged port (it listens on 8444 by default), no elevated capabilities, and writes nothing outside its own log directory.

Linux (systemd)

A ready-made unit file ships with the gateway. Assuming the published output lives in /opt/athena-gateway with its appsettings.json alongside:

# Install and enable the service
sudo install -m 0644 athena-gateway.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now athena-gateway

# Follow the logs
journalctl -u athena-gateway -f

The unit runs a config validation as a pre-start step, so it refuses to start on a bad config rather than restart-looping against one. It runs as a dedicated athena-gateway user, is hardened with the usual sandboxing directives, and sets a stop timeout above the drain window so systemd does not kill the process mid-drain. Keep the unit's stop timeout above Gateway:DrainTimeoutSeconds, and keep the file-descriptor limit above twice Gateway:MaxConnections (each connection uses two sockets).

Docker

A runtime-only container image is provided. Inside a bridged container the listen and health addresses refer to the container's interface — a host LAN or overlay address is not automatically reachable inside the container — so the image defaults both to 0.0.0.0 and expects you to publish the ports and constrain exposure at the host/network layer.

docker run -d --name athena-gateway \
  -p 8444:8444 \
  -p 127.0.0.1:9080:9080 \
  -e Gateway__UpstreamHost=203.0.113.10 \
  -e Gateway__UpstreamPort=8444 \
  athena-gateway:latest

The container stops on SIGTERM and honours the drain window, so allow enough stop grace for established sessions to finish. The image's own health check runs the --validate configuration check.

Windows service

The same binary registers as a Windows service (service name AthenaGateway) when run under the service control manager, reading appsettings.json from its install directory. Configure it the same way and set Gateway:ListenAddress to the interface agents reach it on.

Health & readiness#

The gateway serves liveness, readiness, and metrics on the separate health port (loopback by default). The endpoints return JSON:

Prometheus metrics#

GET /metrics returns standard Prometheus text. Every series carries an instance label identifying the gateway instance. The counters measure sockets and ciphertext bytes, never agents or message contents — the gateway cannot see inside TLS, so no metric is labelled with an agent identity or a remote address.

Useful signals to alert on: a rising rejected_at_capacity_total means you are hitting MaxConnections; a rising upstream_connect_failures_total (or a not-ready readiness probe) means the gateway cannot reach the upstream server.

Logging & troubleshooting#

The gateway logs to the console and to a rolling daily file under its logs/ directory (kept for the last 14 days by default). Payload bytes are never logged — connections are identified only by the gateway instance id plus an ephemeral connection id, never by a guessed agent id. Typical checks:

• Won't start / exits 78: run Athena.Gateway --validate and fix every listed problem; confirm appsettings.json is next to the binary.
• Agents can't connect: confirm ListenAddress/ListenPort are reachable from the agent network and that the Athena hostname resolves to the gateway there.
• Readiness stuck not-ready: the gateway cannot reach UpstreamHost:UpstreamPort — check firewall egress from the gateway host and that the upstream is not the DNS-overridden name.
• Capacity rejections: raise MaxConnections (and the host file-descriptor limit) or add another gateway.