You are viewing the docs for Archestra v1.4. View the latest docs
Connect Your Agents
Connect your AI client once, and Archestra governs everything it does. It gets Archestra's tools, models, and shared skills. Your access rules, Guardrails, cost limits, and logs then apply to it.
- Tools come through the MCP Gateway.
- Model requests go through the LLM Proxy.
- Shared skills install in the client.
Open Connect in the Archestra sidebar and choose how to connect:
- Coding agents: for Claude Code, Codex, Cursor, Copilot CLI, OpenCode, and Kilo Code, you run one command in a terminal and approve the connection in your browser.
- Claude Desktop: a downloadable installer sets up Desktop.
- n8n: you enter the gateway URL and model settings in your workflow.
- Any Client: any tool that supports MCP or an OpenAI-compatible API. Copy the gateway URL, the proxy base URL, a key, and a Git URL for the shared skills.
To leave out the proxy, skills, or plugins, open Setup options on the approval page before you approve. Your admin decides which provider keys the proxy uses for each client.
Guardrails recognize Archestra Chat, Claude Code, Codex CLI, OpenCode, and Kilo Code automatically. Custom clients and workflows need a session header so Guardrails can track their conversations.

Before You Start
For Claude Code, Codex, Cursor, Copilot CLI, OpenCode, and Kilo Code:
- Node.js 18 or newer, and a terminal on the computer where you use the client.
- The client's CLI on your
PATH:claude,codex,copilot,opencode, orkilo. OpenCode must be 1.17 or newer. Copilot CLI proxy setup requires 1.0.95 or newer. - Python 3 for Claude Code and for Cursor's models. Git for Cursor, OpenCode, and Kilo Code skills.
- An Archestra URL on HTTPS. Plain HTTP works only on
localhost.
Connect a Coding Agent
The command changes nothing on your computer until you approve it in your browser.
- On Connect, select your client. For another system, click Use the Windows command or Use the macOS / Linux command.
- Click Copy and run the command in a terminal. It prints a code and opens an approval page in your browser.
- Check that the code in the browser matches the code in the terminal. Tick This code matches the code in my terminal and click Approve connection.
- Back in the terminal, the installer sets up your client and lists what it set up. When it asks Sign in now?, press Enter to sign in to the gateway in your browser.
- When it asks to start your client now, press Enter. Your client starts with a first question about the gateway's tools, leaving your other MCP servers alone. On Windows, or if you answer no, open a new terminal and run the command the installer prints last. Cursor has no command: open Cursor.

Finish Setup in Your Client
Some clients need one more step. The installer prints any other steps under Good to know. <gateway> is the name your client lists for the Archestra gateway.
- Claude Code: if you skipped the sign-in, start Claude Code, run
/mcp, select the gateway, and choose Authenticate. - Codex: if you skipped the sign-in, run
codex mcp login <gateway>. - Cursor: quit and reopen Cursor, then sign in to the gateway under Customize → MCPs. Setup points Cursor's OpenAI API key settings at the Model Router with a virtual key for your model providers. Cursor's model picker then lists only the models the Model Router offers you, such as
anthropic:claude-sonnet-4-6. Setup switches off Cursor's built-in models. Switch one back on under Settings → Models. - Copilot CLI: setup saves your provider settings and available key in
providers.jsonand selects the model insettings.json. If setup reports a missing key, add it toproviders.json. The environment variables printed at the end are optional. - OpenCode: if you skipped the sign-in, run
opencode mcp auth <gateway>. While connected, OpenCode lists only the providers and models Archestra serves you, under their usual names. Amodel,small_or agentmodel modelsetting that Archestra does not serve is ignored, and setup names it. Providers you sign in to from OpenCode itself, such as a ChatGPT or Claude subscription or your own key, also go through Archestra. Restart OpenCode after signing in to one. - Kilo Code: if you skipped the sign-in, run
kilo mcp auth <gateway>. Setup writes its settings to~/.config/kilo/kilo.json. If yourkilo.jsoncalready registers the same gateway under another name, setup disables that duplicate and preserves its comments and connection settings. Providers and models work as for OpenCode, and providers that do not go through Archestra, such as the Kilo Gateway, are turned off while connected.
After Setup
- Launch check: setup adds a block to your shell profile. Each time Claude Code, Codex, Copilot CLI, OpenCode, or Kilo Code starts, it checks the connection. Press
Cthere to disconnect. To turn it off, setARCHESTRA_CLAUDE_GUARD=0,ARCHESTRA_CODEX_GUARD=0,ARCHESTRA_COPILOT_GUARD=0,ARCHESTRA_OPENCODE_GUARD=0, orARCHESTRA_KILO_GUARD=0. - Startup check updates: each launch also checks whether your installed startup check is older than the deployment. If an update is available, it shows why and how to rerun setup, then continues after six seconds. Press any key to continue sooner.
- Backups: setup saves each config file it changes as a
.archestra-backupfile next to the original. - Automatic client helpers: approved OpenCode and Kilo Code setup installs an update loader for the managed launcher helper and routing plugin, using Node.js 18 or newer. Before launch or plugin activation, it refreshes verified code from your connected Archestra deployment over HTTPS and loads that code in the same process. Concurrent starts share a download check for 30 seconds. Failed or offline downloads keep the verified cached code. These updates do not upgrade the client CLI, rerun installation, issue new provider keys, or replace your original backups.
- Duplicate gateways: the launcher and plugin repair equivalent, enabled registrations before tools bind. They match the exact gateway URL, preserve JSONC comments and authentication settings, and leave deliberately disabled or disconnected bindings disabled. Conflicting connection settings stop repair rather than choose credentials for you.
- Existing installations: a launcher installed without the update loader cannot download and execute new code retroactively. Apply an approved setup once to enroll it; subsequent managed helper updates need no setup rerun. The shell-profile wrapper and health-check screen remain installed locally, separate from the automatically updated helper. Plain-HTTP local development uses cached helper code only.
- Guardrail helpers in Codex: setup lets Codex run the guardrail helper tools, such as
ask_anduser yell, without a prompt each time. A call that needs your approval still shows the approval form. To get the prompts back, delete thetoolstables under the gateway's entry in~/.codex/config.toml. - Codex waits for the gateway: Codex 0.99 or newer does not send the first
codex execrequest until the gateway is connected. If you skipped sign-in, or the gateway is down, that command stops. Sign in withcodex mcp login <gateway>, then run it again. Older Codex ignores this and can still send the first request early. To letcodex execstart without the gateway, deleterequired = trueunder the gateway's entry in~/.codex/config.toml. - Setup reference: the first conversation that presents the installer's reference with a valid session ID is exempt from Guardrails for the rest of the ten-minute setup window. Later requests must carry both the reference and that session ID. Different session IDs and requests without the reference remain governed.
- Exemption limits: the first conversation wins, even if it did not run the installer. Session IDs come from the client, so this does not protect against a client that copies both the reference and the session ID. If the server loses the short-lived ownership record, another conversation can claim the rest of the window.
- Setup failed or expired: run it again. Approval requests expire after ten minutes. Only approve a request you started.
Next: See it work.

