Skip to main content

Add an agent

An agent cannot sign in through a browser. Give it a service key, run one command on its host, and watch the Agents card turn Active.

A service key (ark_svc_…) carries its own identity, team, and optional monthly budget. It never counts as a billed seat, so nothing goes in ANYRAY_SEAT_EXCLUDE.

1
Add the agent

On the console's Users page, open the Agents card and choose Add agent. Name it and give it a team (1 to 64 letters, digits, dot, colon, hyphen, or underscore). A Monthly budget is optional: a USD ceiling per UTC month, after which the key's requests get a 402. For a shared agent (a Slack bot, an internal assistant) tick Attribute requests to the people this agent serves: each request then files under the user the agent sends in x-anyray-metadata, and those people count as seats.

2
Copy the key

The ark_svc_… value is shown once. Put it in the host's secret store now; Anyray keeps only its hash.

3
Run one command on the agent's host

The dialog prints this with your gateway URL and key filled in. It points every tool on the host (Codex, Claude Code, OpenCode, OpenClaw) at the gateway under the agent's identity, and registers the Anyray retrieval server for each of them.

export ANYRAY_CLIENT_KEY=ark_svc_…   # from the host's secret store
curl -fsSL https://app.anyray.ai/connect.sh | sh -s -- --gateway https://<your-anyray-gateway> --yes
The agent is connected

Within a minute of its first request, the dialog's last step and the Agents card both read Active with retrieval connected. Last active shows when, and from which tool.

Active · retrieval not seen means requests are landing but no tool on the host can call anyray_retrieve, so trimmed content cannot be read back: open the row and finish step 3 of its Setup tab. Needs gateway upgrade means your gateway predates the connection check; upgrade it, nothing on the host is wrong.

Wire an SDK or a script instead of a host

Code that calls the API itself reads the base URL and key from its environment. Pick the dialect in the dialog's step 2, or set the two variables:

OpenAI dialect
export OPENAI_BASE_URL=https://<your-anyray-gateway>/v1
export OPENAI_API_KEY=ark_svc_…

Then register the gateway's MCP server so the model can read back what optimization set aside: SDKs reference. A sandboxed OpenClaw container that cannot run the installer takes a config file instead: OpenClaw.

Minting from the admin API, routingConfig, the credential header order, managing keys, and the full status vocabulary are on the agent reference.