Registration

An agent proves its identity to AIMO with an asymmetric keypair. Two ways to bind the keypair to an agent record:

1. Register via agent — Run the agent image’s register command with a short-lived registration token from the web UI.
2. Supply a public key — Paste a public key when you create the agent; you keep the private key in your own systems.

Both paths end the same way: AIMO stores the public key; the running agent uses the private key to obtain JWTs. Day-to-day commands and environment variables are in Agent CLI.

Registration binds a keypair once; afterwards every call is authenticated with a short-lived JWT. The private key never leaves your environment, and the registration token is single-use.

Read the diagram top to bottom. The upper half is the one-time pairing that happens when you run register: a keypair is generated next to your agent, only the public key travels to AIMO, and the one-time token is consumed and deleted. The lower half is the ongoing pattern—there is no static API password, so for every REST or WebSocket call the agent proves it holds the private key and receives a short-lived JWT that AIMO checks against the stored public key. The sections below walk through each step.

Register via agent (registration token)

In Add agent, choose Register via agent. You set a name and TTL in days for the agent authorization; you do not paste a public key. On create, AIMO allocates an agent UUID and stores a registration token (short-lived, keyed to that UUID).

The UI shows a Docker command that runs register with that token. Example (adjust image registry/tag for your deployment):

docker run --pull always --rm -u "$(id -u):$(id -g)" -v ./:/app/data rg.nl-ams.scw.cloud/aimo/agent:latest register <REGISTRATION_TOKEN>

What register does

1. Generates an Ed25519 keypair locally. The private key does not leave your environment until you decide where it lives.
2. POSTs to /api/v1/agents/registration with the token and base64-encoded public key. The server validates the token, attaches the public key, sets key expiry, records registered at, stores the public key for authentication, and deletes the token so it cannot be reused.
3. Optionally tests authentication against the token endpoint and reports success or a warning.
4. Writes aimo_agent.sh into the mounted data directory (/app/data in the container → your host path when using -v ./:/app/data).

What aimo_agent.sh contains

A small bash script that:

• Exports AIMO_AGENT_UUID from the server response.
• Exports AIMO_AGENT_PRIVATE_KEY_B64 (the generated private key).
• Exports AIMO_AGENT_PASSPHRASE (random hex by default) used to encrypt connection credentials in the CLI—you may replace it with a passphrase you manage.
• Exports AIMO_AGENT_HOST and AIMO_AGENT_USE_TLS (matching the server you used when registering) so REST and WebSocket URLs agree.
• Runs docker run with -v ./:/app/data, passes those env vars into the agent image, and forwards "$@" so you can run subcommands such as start.

chmod +x aimo_agent.sh
./aimo_agent.sh start

Treat aimo_agent.sh and anything containing AIMO_AGENT_PRIVATE_KEY_B64 as secrets.

Token visibility and rotation

The registration token is shown only at creation (as documented in the UI). Use update agent key / a new registration token when you need to register a new keypair.

Supply a public key

In Add agent, choose Supply public key. You set the same name and TTL and paste a base64-encoded public key. Supported types follow the server’s parse_public_key logic (including Ed25519 and RSA with optional type hints).

AIMO stores the public key immediately. No registration token. You generate the keypair outside the product, keep the private key in your vault, and configure AIMO_AGENT_UUID and AIMO_AGENT_PRIVATE_KEY_B64 for that agent.

Suited to HSMs, internal PKI, or config systems that provision keys without running register.

Choosing a path

	Register via agent	Supply public key
Where the keypair is created	register CLI inside your run	You create it; only the public key is sent
First step	Docker register with token, then aimo_agent.sh or equivalent env	Configure UUID + private key; no register
Best when	You want a one-time token and a generated wrapper script	You must meet existing key custody or policy

After registration, see Agent CLI and Operations for connections and the long-running agent process.