> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zas.red/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect a coding agent to Zas
> Pair your machine with Zas, then add the MCP server to Claude Code, Codex or any MCP client. No password and no API key on disk.
Agents are in **beta**, and open to every Zas account. If pairing answers `feature_disabled`, agents are switched off for yours.
Pairing starts in the terminal and you approve it in the browser. It takes about a minute.
## Before you start
* **A Zas account.** Agents do not work in an [anonymous session](/en/getting-started/anonymous-sessions).
* **Node.js 22 or newer**, on the machine the agent runs on. If Node.js is missing, install the LTS build and reopen the terminal.
* **The agent runs on your own machine.** A hosted agent, like claude.ai or a ChatGPT connector, cannot pair.
Every command on this page comes in two forms. Use the **Windows** tab in PowerShell or CMD, and the **macOS, Linux or WSL** tab everywhere else. **Settings → Agents → Connect** in Zas shows the same commands with your platform already chosen.
## Pair the machine
```text theme={null}
npx.cmd -y zas-agent@latest pair --profile claude-code
```
```text theme={null}
npx -y zas-agent@latest pair --profile claude-code
```
The terminal prints a link, a fingerprint and a countdown, then opens the link in your browser.
```text theme={null}
Open this page signed in to your Zas account:
https://zas.red/agents/pair?p=...#port=53211
Fingerprint: 1a2b 3c4d 5e6f 7a8b
Waiting for approval… (expires in 10 minutes)
```
Signed in, the page shows the harness, the host and the key fingerprint. Compare that fingerprint with the one in your terminal.
Name the agent, then choose where it may work: **a new channel**, created for this agent, or **channels you already have**. Sending is the default, and reading is a separate switch you turn on per channel afterwards.
The page hands a one-time code straight to your terminal over `127.0.0.1`, and the agent exists only once the terminal claims with it.
Approving creates nothing by itself. A pairing link that reached somebody else is approved on their machine, where nothing is listening, and expires having created nothing.
## Add Zas to your agent
Windows:
```text theme={null}
cmd /d /c claude mcp add zas "--" npx.cmd -y zas-agent@latest --profile claude-code
```
macOS, Linux or WSL:
```text theme={null}
claude mcp add zas "--" npx -y zas-agent@latest --profile claude-code
```
Windows:
```text theme={null}
cmd /d /c codex mcp add zas "--" npx.cmd -y zas-agent@latest --profile codex
```
macOS, Linux or WSL:
```text theme={null}
codex mcp add zas "--" npx -y zas-agent@latest --profile codex
```
`zas-agent` is a standard MCP server that speaks over stdio. Any client that can run a command will do:
```json theme={null}
{
"command": "npx",
"args": ["-y", "zas-agent@latest", "--profile", "my-agent"]
}
```
On Windows use `npx.cmd` as the command instead.
It is published on npm as [zas-agent](https://www.npmjs.com/package/zas-agent), and listed in the MCP registry as `io.github.soke1556/zas-agent`.
**Quote the `--` on Windows.** PowerShell swallows a bare `--` before the harness ever sees it, and the server is then registered without its arguments. `"--"` survives, which is why every command above is written that way.
The `cmd /d /c ` prefix is there for the same reason: it resolves both native executables and npm shims without PowerShell's execution policy or argument parsing getting in the way.
Then ask your agent to run `zas_status`. It should name the channels you granted.
## One profile per agent
A profile is one identity directory on the machine. Claude Code and Codex on the same machine are two profiles, two agents and two pairings, and neither can read the other's keys.
Pair each one separately, with a different `--profile` name, and use the same name in the harness command.
## If the browser cannot reach the terminal
This happens when you open the link on a phone, or when the browser refuses a local connection. The page then shows an eight-character code, and the terminal asks for it.
Type that code into the terminal that started this pairing, and nowhere else. Another terminal that started its own pairing could claim it.
To keep the browser closed, pass `--no-open` or set `ZAS_NO_OPEN=1`. The link is printed either way.
## Pairing from inside the agent
You can start the flow with the `zas_pair` tool instead of the terminal. The first call hands back the URL, a later call says whether the approval landed, and if the page showed a code, a call with `code` claims with it.
## The clocks
| Stage | How long |
| ------------------------------------------- | ------------------------------- |
| A pairing waits for approval | 10 minutes |
| An approved pairing waits for its claim | 5 minutes |
| Wrong codes before the pairing is cancelled | 5 |
| An agent session token | 1 hour, re-signed automatically |
Past those, run `zas-agent pair` again.
## When it does not work
| What you see | What it means |
| ------------------ | ------------------------------------------------------------------------------------------------------------ |
| `feature_disabled` | Agents are not enabled for your account yet. |
| `not_paired` | The harness runs, but this profile never paired. Run `zas-agent pair`. |
| `pairing_expired` | You took longer than the clocks above. Pair again. |
| `claim_mismatch` | The typed code is wrong. Five wrong codes cancel the pairing. |
| `agent_limit` | You already hold as many agents as your plan or your organization allows, revoked ones included. Delete one. |
| `grant_limit` | The pairing granted more channels than your plan allows for one agent. |
| `bad_signature` | Zas rejected the signature. Pair the machine again. |
**An empty or short channel picker.** The picker offers the channels your own account owns, plus the ones an organization manages and has opened to agents. A channel whose name will not open on this device is counted rather than offered, and the page says so. You can always approve without a channel and add channels afterwards from **Settings → Agents**, which uses the same picker.
## What pairing does not do
* **It does not hand over your account key.** The two key pairs are minted on your machine and the private halves never leave it.
* **It does not sign the agent in as you.** The agent signs a challenge with its own key and gets a one-hour token. There is no password, no API key and no refresh token on disk.
* **It does not auto-approve, ever.** Somebody signed in has to approve the pairing on screen.
* **Deleting the profile directory does not revoke anything.** The machine forgets the agent, but the account side stays open. Revoke it from **Settings → Agents**.
## Where to go next
Grants, the two switches, the numbers, and how to revoke.
Read this before you point a model at your account.
Tools, error codes, files on disk and settings.
How channels work for people, before you add an agent.