zas-agent

An MCP server that lets a coding agent — Claude Code, Codex, or anything that speaks MCP — send files and notes into your Zas channels, and read items back out of them.

What is Zas

Zas moves things between your devices and the people you choose: files, photos, text, code. You put something into a channel on one device and use it on another. Whatever you do not pin leaves on its own after a few days, so there is nothing to tidy up later. Everything is encrypted on the device before it is uploaded: the database and the object storage receive encrypted bytes, not filenames, content or previews.

This package is the piece that lets a coding agent use your channels the way your other devices do, under an identity of its own that you approve, that you scope to the channels you choose, and that you can revoke.

What it does

Your coding agent gets eleven tools. It can send a file or a note into a channel you picked, send or receive a file live through Directo, list what is in that channel, and pull one item back onto disk. Everything it sends is encrypted on your machine before it leaves, lands in your account, and is marked in the channel as sent by that agent. The agent has an identity of its own and never holds your account key: pairing mints a key pair here, you approve it from the web app, and from then on it signs a challenge to get a short-lived session.

Install

Install Node.js LTS (22 or newer) and your agent's command-line tool first. Reopen your terminal after installing. Run these commands on the computer where you use the agent.

Choose your agent and pair it. On Windows (PowerShell or CMD):

Codex

npx.cmd -y zas-agent@latest pair --profile codex

Claude Code

npx.cmd -y zas-agent@latest pair --profile claude-code

Open the printed link, approve the channels, and enter the code in the terminal if the page shows one. Leave the terminal open until pairing finishes. Then run the matching registration command:

Codex

cmd /d /c codex mcp add zas "--" npx.cmd -y zas-agent@latest --profile codex

Claude Code

cmd /d /c claude mcp add zas "--" npx.cmd -y zas-agent@latest --profile claude-code

On macOS, Linux, or WSL, use npx in place of npx.cmd and omit cmd /d /c . Pair and register in the same environment. Restart your agent and ask it to send something to Zas.

If a command is not recognized, install Node.js or the named agent's CLI and reopen the terminal. The first download needs internet access and may take a few minutes. Use @latest as shown so npm requests the published package instead of selecting an unbuilt local workspace.

What pairing does

zas-agent pair mints the key pair, registers the public halves, opens the approval page in your browser, and waits. The terminal shows:

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, name the agent and tick the channels it may use — sending is the default, reading is a separate switch — and approve. Approval creates nothing by itself: the page hands a one-time claim code to this terminal over 127.0.0.1 (the port in the link), and the agent exists only once the terminal claims with that code and the secret it holds. A link that reached somebody else is approved on their machine, where nothing listens, and expires with nothing created.

If the browser cannot reach the terminal — the link was opened on a phone, or the browser refused the local connection — the page shows the code and the terminal asks for it. Type it there and nowhere else: with that code, another terminal that started a pairing could claim it. Pass --no-open or set ZAS_NO_OPEN=1 to keep the browser closed; the link is printed either way. The pairing is good for ten minutes before approval and five after; past that, run the command again.

You can also start the flow from the coding agent with the zas_pair tool: the first call hands back the URL, a later call says whether the approval landed, and if the page shows a code, a call with code claims with it.

Why you can trust it

Every line here is a fact. The ones about this package you can check in this repository. Where a property is enforced by the Zas server, which is not open source, the sentence says so.

• The agent has an identity of its own. zas-agent pair generates two key pairs on your machine — X25519 to receive channel keys, P-256 to sign sign-ins — and the private halves never leave it. The agent never holds your account key, and the key-derivation service refuses account-key derivation to an agent (server-side).
• You approve it, and you choose the channels. Pairing never auto-approves. The approval page shows the harness, the host and the key fingerprint, and nothing exists until the terminal that started the pairing claims it with a code only the approving page received (server-side). A pairing link sent to you by someone else creates nothing on your account.
• It holds one key per granted channel, and no key for any other. Each grant carries that channel's key sealed to the agent's X25519 public key. A channel you did not grant has no key here to decrypt with, and the server checks the live grant on every request (server-side).
• No password and no API key. Signing in is a signed challenge traded for a one-hour token. There is no password, no API key and no refresh token on disk: the agent re-signs from its P-256 key when the token ages out.
• Everything it sends is visible as its work. Every item carries the >_ agent mark and the agent's name, in the channel, on every device you read Zas from.
• You can revoke it at any time. Settings → Agents → the agent → Revoke. The session stops, its refresh tokens are revoked (server-side), and the next tool call answers "the owner revoked this agent". What it already sent stays where it is. You can also drop a single channel and keep the rest.
• Content is encrypted on your machine before it leaves, the same way the app does it. The chunking, the manifest and the envelope formats under src/shared/ are the same modules the Zas web app ships. The server stores ciphertext and never sees a channel key, a channel name or item plaintext (server-side).
• The source is here, and the releases are built from it. Every npm release is published by the release.yml workflow in this repository, with npm provenance, so the tarball on npm can be traced back to a commit and a workflow run.

What it cannot do

The package refuses some of these on its own, before a request is made. The ones marked (server-side) are enforced by the Zas server.

• No channel you did not grant. Not by name, not by id.
• No shared channel you merely joined, and no workspace channel. Grants exist only on channels your account owns and that no organization manages (server-side).
• No reading unless the grant says so. read is a separate switch from send; without it, zas_list_items and zas_get_item are refused.
• No stored sending into a view-only channel, and none into a channel in Directo mode. Both are refused before a byte is uploaded. A channel in Directo mode takes zas_send_direct, a live transfer that stores nothing.
• No receiving unless the grant says read. Receiving through Directo writes a file onto this machine, so zas_receive_direct takes the same read switch as listing. And it only ever runs inside a tool call: the agent never watches your channels, so nothing arrives unasked.
• Nothing outside its allowlist. The API refuses an agent on every route that is not on a short, explicit list, and Firestore rules refuse it your account document, your devices, and any channel without an active read grant (server-side).
• Rate limited by the server, on its own buckets, with the key-derivation budget charged to your account so ten agents are not ten times your own allowance (server-side).
• As many agents as your plan or your organization allows (server-side).
• Files up to 5 GiB, and in practice less: the agent reads a file into memory to hash it, so the machine's memory is the real ceiling.

The error vocabulary

The agent answers in a closed set of codes. Anything a server route says that is not in this set collapses to upload_failed or network, so no raw server string ever reaches a terminal.