Skip to main content

Add an agent

An agent cannot sign in through a browser. Give it its own key, run one command on its host, and verify the connection in the Agents card.

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

1
Add the agent

On the console's Users page, open the Agents card and choose Add agent. Give it a name and a team. Both take 1 to 64 characters from A-Z a-z 0-9 . : - _.

2
Copy the key

Put the ark_svc_… value in the host's secret store. Anyray keeps it sealed at rest, so you can show it again later from the agent's Setup tab.

3
Run one command on the agent's host

The dialog prints this with your gateway URL and key already filled in:

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

It points every tool on the host at the gateway under the agent's name, and it registers the retrieval server for each one. Claude Code also gets its source hook, which runs before tool output enters the transcript. SDK sessions on a managed Claude host inherit its hook settings.

4
Verify the connection

Within a minute of the agent's first request, the Agents card reads Active, and Last active shows when and from which tool. Two other results mean something is wrong:

  • Active · retrieval not seen. Requests land, but no tool on the host can call anyray_retrieve, so the agent cannot read back trimmed content. Open the row and finish step 3 of its Setup tab.
  • Source hook missing. Upgrade Connect. The source hook is reported separately from retrieval. Source hook not reported means no recent host report has arrived.
  • Needs gateway upgrade. Your gateway is too old to run the check. Upgrade it. Nothing on the host is wrong.
The agent is connected

The Agents card reads Active with retrieval connected, and the agent's spend now lands under its own name in the console.

Let a coding agent set the host up

Whoever wires an agent host is usually working through a coding agent already. Give it this page and it runs every step above, including the retrieval check:

https://app.anyray.ai/agent-host.md

It will ask you for the gateway origin, and it will ask you to put the key in the host's environment yourself. Do not paste an ark_svc_ key into the conversation. The runbook carries no organization details, so the link is safe to share with anyone already setting up the host.

You no longer have the key

Open the agent's row, go to Setup, and choose Show key. Anyray keeps each agent's key sealed at rest, so the setup steps fill in with the real key whenever you need it again. Every read is recorded in the audit log, and the button appears only for an operator whose session may read keys back (security_admin and up).

Two agents have nothing to show: one created before Anyray stored keys, and one on a deployment with no admin token to seal a key with. Both offer Generate a new key instead. That keeps the agent's name, team, budget and routing, and the old key stops working right away, so anything already running under it needs the new one.

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 wire the source hook beside the gateway's MCP server so trimming and read-back belong to the same agent setup: SDKs reference. A sandboxed OpenClaw container that cannot run the installer takes a config file instead: OpenClaw.

A tool-loop key also shows whether source trimming has been seen. The row offers a copyable host repair and polls for the result. Source-trim setup and grace period.