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:
Full configuration via CLI flags:
Production with structured 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.
Related material¶
- Platform API — the
aetelier.v1beta1Gateway wire and auth surface. aetelier-connect— the worker primitives the agent spawns from manifests.aetelier-telemetry— metric vocabulary the agent populates upstream.