Skip to content

aetelier-agent

The Aetelier remote-agent binary. A long-running Rust process that connects to the Aetelier Gateway over gRPC, accepts work assignments (TOML manifests for data and market workers), spawns the workers, and streams telemetry + artifacts back upstream.

The agent is binary-only (publish = false). It has no library API and no docs.rs page. This page is the canonical reference for operating it.

Source

Quoted material reflects the aetelier-agent published as ghcr.io/aetelierxyz/aetelier-agent:latest, the image the webapp's deploy command runs.

Identity model

Three identity fields shape every agent run:

Field Where it comes from
binding_id Embedded in the JWT, minted by the Overseer at deploy time
service_id Embedded in the JWT
session_id Embedded in the JWT
agent_id Allocated by the Gateway at registration, returned in RegistrationResponse.Accepted
agent_alias User-facing label, auto-generated as RA-<uuid> if not provided

The agent consumes a pre-issued JWT — it does not self-sign. binding_id, service_id, and session_id are extracted from the token's claims and are not separate environment variables. The authoritative agent_id is the Gateway's, not anything the operator provides.

Environment variables

Env var CLI flag Default Required
AETELIER_GATEWAY_URL --gateway-url http://localhost:50443 no
AETELIER_TOKEN --token — yes
AGENT_ALIAS --agent-alias auto-generated RA-<uuid> no
RUST_LOG — info no

AGENT_ID is not read

Earlier iterations of the agent accepted an AGENT_ID env var. That has been removed. The Gateway allocates the authoritative agent_id and returns it in the registration response. Setting AGENT_ID has no effect.

CLI flags

aetelier-agent [OPTIONS]

OPTIONS:
      --gateway-url <URL>      Gateway gRPC URL
                               [env: AETELIER_GATEWAY_URL]
                               [default: http://localhost:50443]

      --token <JWT>            Pre-issued JWT (the `token` field from the
                               webapp's deploy response).
                               [env: AETELIER_TOKEN]
                               (required — agent does not self-sign)

      --agent-alias <NAME>     User-facing label; auto-generated if omitted.
                               Never load-bearing — Gateway-allocated
                               agent_id is authoritative.
                               [env: AGENT_ALIAS]

      --json-logs              Emit structured JSON logs (recommended in
                               production).

  -h, --help                   Print help
  -V, --version                Print version

Typical invocations

Minimum, JWT via env var:

AETELIER_TOKEN=eyJhbGc... aetelier-agent

Full configuration via CLI flags:

aetelier-agent \
  --gateway-url http://gateway:50443 \
  --token eyJhbGc...

Production with structured logs:

aetelier-agent --json-logs

RUST_LOG=info,aetelier_connect=debug is a common debug filter.

Where the JWT comes from

The webapp's "Deploy agent" UI (the Spawn Modal's credential panel) returns a JWT minted by the Overseer at deploy time. Operators copy that token into the AETELIER_TOKEN env var on the host where the agent will run. The token's claims include binding_id, service_id, and session_id — the agent reads them at startup; signature verification happens at the Gateway, not in the agent.

The Gateway verifies the token's signature on every connection attempt. The agent does not have, and does not need, the signing key.

Lifecycle

sequenceDiagram
    autonumber
    participant Op as Operator (you)
    participant Web as Webapp UI
    participant Over as Overseer
    participant Gate as Gateway
    participant Ag as aetelier-agent

    Op->>Web: "Deploy agent"
    Web->>Over: Mint JWT
    Over-->>Web: token
    Web-->>Op: token

    Op->>Ag: AETELIER_TOKEN=… aetelier-agent

    Ag->>Gate: Register (gRPC)
    Gate-->>Ag: agent_id, manifest

    Ag->>Ag: Spawn workers per manifest
    loop streaming
      Ag->>Gate: Telemetry envelopes
      Ag->>Gate: Artifact envelopes
    end

    Gate->>Ag: Lifecycle command (pause / resume / stop / restart)
    Ag->>Ag: Apply
    Ag->>Gate: Acknowledge

    Op->>Ag: SIGINT (Ctrl-C)
    Ag->>Gate: Final report + close

Lifecycle commands the Gateway can send

Command Effect
pause Workers stop emitting events but keep their connections alive.
resume Workers resume emission.
stop Workers shut down cleanly. Agent exits.
restart Workers shut down and respawn from the same manifest.

These mirror the lifecycle verbs the platform sends over CommandChannel, documented on the Platform API page.

Telemetry channel

The agent streams a single unified upstream Envelope channel that multiplexes telemetry samples and artifact bytes. Buffer capacity defaults to 256 envelopes, which absorbs both metric-burst peaks and artifact flushes without backpressuring the worker loop. The RemoteAgentConfig::telemetry_buffer field is exposed for tuning if necessary.

The metric vocabulary itself is from aetelier-telemetry: MESSAGES_RECEIVED, EVENT_LATENCY_MS, WORKER_CONNECTION_STATE, SINK_QUEUE_DEPTH.

Deployment — Docker

The webapp shows the exact command for each binding, on the deploy confirmation and again in the fleet's command view:

docker run -d --pull always --restart unless-stopped --name aetelier-agent-<exchange>-<datatype>-<binding4> \
  -v "$HOME/aetelier-data:/home/agent" \
  -e AETELIER_GATEWAY_URL="<gateway_url>" \
  -e AETELIER_TOKEN=<token> \
  -e RUST_LOG=info \
  ghcr.io/aetelierxyz/aetelier-agent:latest

The container name is aetelier-agent- followed by the exchange id, the datatype (orderbook, trades, or data), and the first four characters of the binding_id. --pull always keeps the cached :latest image in step with the gateway's wire contract, and --restart unless-stopped keeps the collector running across host reboots and daemon restarts. The volume keeps the agent's working directory, /home/agent, on the host. A stopped container keeps its name: run docker rm -f <name> before running the command again.

Common operational issues

The agent exits with error: registration rejected. The Gateway rejected the JWT. Causes: token expired, token not minted against the Gateway's current signing key, binding_id already in use by another active agent. Resolution: mint a fresh token from the webapp's Spawn Modal.

The agent connects but spawns no workers. The manifest the Gateway sent has no [[workers]] entries, or all entries failed to resolve. Check the agent's logs for workers.spawn_failed events.

Telemetry envelopes back up. The upstream Envelope channel is full (default 256 capacity). Either the Gateway is consuming slowly or worker output is bursty. Bump RemoteAgentConfig::telemetry_buffer and rebuild, or investigate Gateway-side ingestion latency via the aetelier-telemetry SINK_QUEUE_DEPTH metric.