Add an agent
Give an unattended agent its own key, run one command on its host, verify in the Agents card.
A service key (ark_svc_…) has its own identity, team, and optional budget, and is never a billed
seat.
Console Users page > Agents card > Add agent. Name and team each take 1 to 64
characters from A-Z a-z 0-9 . : - _.
Store ark_svc_… in the host's secret store.
The dialog prints it prefilled:
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
Every tool on the host gets the gateway, the retrieval (MCP) server, and the Anyray skill. Claude Code also gets the source hook.
A route without the anyray MCP server (e.g. Codex beside Claude Code) still works, but cannot read back trimmed content.
Within a minute of the first request the Agents card reads Active. Otherwise:
| Card shows | Fix |
|---|---|
| Codex ✓ · Claude Code: MCP missing | The named runtime cannot call anyray_retrieve. Open the row, finish step 2 of its Setup tab for that runtime. |
| MCP disconnected | No runtime can call anyray_retrieve. Same fix, for all of them. |
| Source hook missing | Upgrade Connect. Source hook not reported means no recent host report. |
| Needs gateway upgrade | Upgrade the gateway. The host is fine. |
An MCP state lasting over a day also shows in sidebar Errors and emails the billing contact
or owners once. All states: status vocabulary.
On the host, anyray-connect doctor --json reports builtinSkill.kind as "ok", or a remedy.
Its spend lands under its own name.
Let a coding agent set the host up
Every Add agent tab leads with a prompt for a coding agent. The Host and OpenClaw tabs give it this runbook:
https://app.anyray.ai/agent-host.md
Put the key in the host environment yourself; never paste an ark_svc_ key into the chat.
| Host | Runbook does |
|---|---|
| Can run the installer | Step 3 |
| Cannot (hardened container, own model loop) | Per route: base URL and key from env, anyray MCP at <gateway>/mcp, org skills from GET /connect/policy |
| Both, after | Polls GET /connect/self-check until every runtime is wired; records runbookVersion and skillVersion, re-reads when newer |
Code built on an SDK or a framework gets the runbook for its tab:
| Tab | Runbook |
|---|---|
| OpenAI | https://app.anyray.ai/agents/openai.md |
| Anthropic | https://app.anyray.ai/agents/anthropic.md |
| LangChain | https://app.anyray.ai/agents/langchain.md |
| LangGraph | https://app.anyray.ai/agents/langgraph.md |
You no longer have the key
Row > Setup > Show key (security_admin and up; audit-logged). Older agents, or a
deployment with no admin token, offer Generate a new key: same name, team, budget, and routing;
the old key stops working within a second.
Wire an SDK or a script instead of a host
Use the dialog's step 2, or set two env vars. They are enough for most code:
- OpenAI dialect
- Anthropic dialect
export OPENAI_BASE_URL=https://<your-anyray-gateway>/v1
export OPENAI_API_KEY=ark_svc_…
export ANTHROPIC_BASE_URL=https://<your-anyray-gateway>
export ANTHROPIC_AUTH_TOKEN=ark_svc_… # no /v1; the SDK appends it
| Code | Needs |
|---|---|
| Only sends requests | Nothing more. |
| Runs its own tool loop | Retrieval-dependent trims stay off without a read path. Other transforms can still run (SDKs). |
| LangChain or LangGraph | The base URL, the key, and one header: LangChain and LangGraph. |
| Claude Agent SDK app | The Anthropic runbook: settingSources: [], and the anyray skill in the app's own plugin. |
| Sandboxed OpenClaw container | A config file: OpenClaw. |