AIMO Docs

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; every call afterwards is authenticated with a short-lived JWT A sequence between the AIMO agent in your environment and AIMO's cloud. One-time registration: the cloud issues a registration token through the web UI, valid for one hour and single use; the agent generates an Ed25519 keypair locally and keeps the private key; it posts the public key with the token; the cloud stores the public key, sets its expiry and deletes the token; the cloud returns the agent's UUID and the agent writes aimo_agent.sh. Every call from then on: the agent sends a timestamp signed with its private key; the cloud checks the signature against the stored public key and that it is recent; and returns a short-lived JWT that REST calls and the job channel carry. AIMO agent, your environment AIMO ONE-TIME REGISTRATION A registration token, from the web UI valid for one hour, single use Generates an Ed25519 keypair. The private key stays here. The public key and the token POST /agents/registration Stores the public key with its expiry and deletes the token. The agent's UUID Writes aimo_agent.sh with the UUID, the private key and a passphrase. EVERY CALL, FROM THEN ON A timestamp signed with the private key POST /agents/tokens Verifies the signature with the stored public key; recent only. A short-lived JWT REST and the job channel carry it
Registration binds a keypair once; afterwards every token the agent holds was earned by proving it has the private key. 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 the agent signs a timestamp with the private key, AIMO checks it against the stored public key and issues a JWT valid for six hours, and the agent signs again before it expires. The sections below walk through each step.

Register via agent (registration token) ​

Under Connections, press Add agent. Register via agent is the default: you set a name and press Create agent; you do not paste a public key. On create, AIMO allocates an agent UUID and stores a registration token (valid for one hour, keyed to that UUID). No key is attached yet: the key and its expiry are set when you run register, with the server's default lifetime of 365 days.

The dialog then shows a Docker command that runs register with that token, ready to copy. Copy it from the UI rather than typing it: the image it names is the one built for the AIMO environment you are signed in to, and that image connects to that environment by default. Example (the production image; the dev environment hands out …/aimo/agent-dev:latest):

bash
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 /agents/registration with the token, the base64-encoded public key, and its type. The server validates the token, attaches the public key, sets the key's expiry, records the registration time, and deletes the token so it cannot be reused.
  3. Tests authentication by minting a JWT from POST /agents/tokens and reports success or a warning. Registration still succeeds even if this check fails.
  4. Writes aimo_agent.sh into the mounted data directory (/app/data in the container, your host path when using -v ./:/app/data). If the directory is read-only, register prints the script contents instead so you can save it yourself.

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, used to encrypt connection credentials in the CLI: random hex for a new agent (replace it with a passphrase you manage), and for a new key of an existing agent the passphrase it already has, so its stored connections stay readable.
  • Exports AIMO_AGENT_HOST and AIMO_AGENT_USE_TLS, matching the server you registered against, so REST and WebSocket URLs agree.
  • Runs docker run of the same image register ran from (its header names it and the server), with -v ./:/app/data, an interactive terminal and --pull always, passes those env vars into the agent image, and forwards "$@" so you can run subcommands such as start.
bash
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 once and expires after one hour. For a fresh one, or to register a new keypair later, press the key button on the agent's row under Connections: the same two steps give you a new register command, and the agent's current key keeps working until it runs. The same button replaces a supplied public key, which takes effect at once.

Supply a public key ​

Under Add agent, choose Supply public key. You set a name, paste a public key and set its lifetime in days. The server accepts OpenSSH (ssh-ed25519 …, ssh-rsa …), PEM (-----BEGIN …), or raw base64 (with an optional type hint); both Ed25519 and RSA keys are supported.

AIMO stores the public key immediately and sets its expiry from the TTL you chose. 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. After Create agent the dialog shows the Docker command that runs start with the new agent's UUID; set AIMO_AGENT_PRIVATE_KEY_B64 in your shell before running it.

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

Choosing a path ​

Register via agentSupply public key
Where the keypair is createdThe register CLI inside your runYou create it; only the public key is sent
First stepDocker register with the token, then aimo_agent.sh or equivalent envConfigure UUID and private key; no register
Key expiryThe server default, 365 daysThe TTL you choose
Best whenYou want a one-time token and a generated wrapper scriptYou must meet existing key custody or policy

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