Skip to content

Platform API

The Aetelier platform separates the control plane from the wire:

Component Repository Role
Control plane atelier-overseer Serves the REST surface: session, service, and binding lifecycle. Mints the JWT an agent presents at registration.
Wire atelier-gateway Speaks the gRPC contract to remote agents: registration, commands, telemetry, artifacts, and lifecycle events.

This page documents the public integration surface — how an operator brings up a remote agent and how that agent talks to the platform. The agent-facing wire is the gRPC contract in atelier-proto; the agent binary and its handshake are documented on the operations pages.

  • Wire protocol — the atelier.v1beta1 Gateway service and its message shapes.
  • atelier-agent — the remote-agent binary: CLI flags, environment variables, and the gateway/JWT handshake.
  • SDK reference — the worker primitives an agent spawns from a manifest.

Authentication

A remote agent presents a pre-issued JWT to the Gateway at registration. The Overseer mints the token at deploy time; the agent consumes it and never self-signs. The Gateway verifies the signature on every connection attempt using a key shared with the Overseer.

The token's claims carry the identities an agent run is scoped to:

Claim Type Description
sub UUID User ID
session_id UUID Session the agent binds to
service_id UUID Service the agent serves
binding_id UUID Binding minted at deploy
exp unix timestamp Token expiration
iat unix timestamp Issued-at

The agent extracts session_id, service_id, and binding_id from the token — they are not separate environment variables. The authoritative agent_id is allocated by the Gateway and returned in RegistrationResponse.Accepted.

Where the token comes from

Operators copy the token from the webapp's "Deploy agent" response into the agent's ATELIER_TOKEN environment variable. See atelier-agent.

The wire — atelier.v1beta1 Gateway

Every cross-boundary message is a gRPC Envelope on the Gateway service. The service exposes three RPCs:

RPC Shape Carries
CommandChannel bidirectional stream of Envelope Registration (first frame), then Manifest / Command and their acks; downstream Commands from the platform
TelemetryChannel client stream of Envelope returning Ack Heartbeat, AgentStatus, TaskTelemetry, ArtifactFrame
EventSubscribe EventSubscribeRequest returning a server stream of Envelope session-scoped lifecycle Events

The message shapes — Registration, Manifest, Command, telemetry frames, ArtifactFrame and its lineage, and the lifecycle Event families — are specified in the wire protocol reference.

Package

The current contract is atelier.v1beta1. Consumers pin a specific tag or git revision of atelier-proto.

Lifecycle commands

The platform sends lifecycle verbs to a running agent over CommandChannel. Each is acked by command_id:

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

See atelier-agent lifecycle for the full handshake and the operator's view of these commands.

Agent configuration

The remote agent reads a small set of environment variables. The full contract — CLI flags, defaults, and the identity model — is on the atelier-agent page.

Env var Default Required Description
ATELIER_GATEWAY_URL http://localhost:50051 no Gateway gRPC URL
ATELIER_TOKEN — yes Pre-issued JWT from the deploy response
AGENT_ALIAS auto-generated no User-facing label
RUST_LOG info no Tracing / logging filter

Dev placeholders

Any token or signing secret shown in examples is a development placeholder, not a usable credential. Production tokens are minted per deploy by the Overseer and are never checked into source or reproduced in documentation.