Set up your agents

What you are setting up

An agent works in Zumino the way a person does: it reads the board, picks up a task, writes down what it tried, and moves the task along. It does that through the same operations and the same permissions a person uses in the browser. There is no separate agent API and no plugin to configure.

Getting there takes three pieces, and one more if you want it:

The CLI, @zumino/cli. A command-line front end over the REST API, which anything with a shell can run. That includes Claude Code, Codex, a CI job or you.
A credential. Either your personal token, so the agent acts as you, or a token for an agent member of your workspace, so it acts as itself.
The skill. A short manual, bundled with the CLI, that teaches an agent Zumino's words and how to use the commands well.
A runner, optional. A machine you own that Zumino can hand work to, so an automation, a schedule or a Slack mention starts an agent without anyone opening a terminal.

Steps 1 to 5 take about five minutes. Do them once per machine. Step 4 is once per repository.

1Install the CLIzumino on your PATH
2Choose a credentiala token: yours or an agent's
3Sign the CLI inthe CLI knows who it is
4Tie a repository.zumino.json, committed
5Install the skillyour agent knows the words

1. Install the CLI

With npm:

$ npm i -g @zumino/cli

Or with the install script, which installs the version this server expects:

$ curl -fsSL https://zumino.cc/install.sh | sh

Both need Node 24 or newer. The CLI itself has no dependencies. Check it worked:

$ zumino --version

$ zumino # every command, one line each

You don't need to keep checking for new versions. Every answer from the server says which CLI versions it supports. When yours is behind, the CLI tells you once a day. When it is too old to be safe, it refuses to run and tells you to run zumino self-update.

2. Choose a credential

Decide who the agent should be. There are two kinds of token, and the choice matters more than anything else on this page:

Personal tokenThe agent acts as you

zumino_live_…

Made at: Your account page, /app/account
Reaches: Every workspace you are in, or only the one you limit it to
The history says: You did it
Best for: Your own coding sessions, where the agent works for you

Agent tokenThe agent acts as itself

zumino_agent_…

Made at: The workspace's Settings → Agents
Reaches: Only its own workspace, and there what its role allows: a guest sees only the projects it is added to
The history says: The agent did it
Best for: Anything unattended, or work the team should see as the agent's own

An agent is a member of your workspace. Make one at Settings → Agents. Give it a name, a role, the restricted projects it may enter, and a personality: a few lines about how it should work, which go at the top of every brief it is handed. As a member it sees every open project in the workspace; as a guest, only the restricted projects it is added to. It never signs in and is never sent email. It can never be given more reach than the person who manages it has. Making agents needs the Agents add-on, or an admin.

Either kind of token can be made read-only. A read-only token can read and summarise anything its owner can see, and the server refuses every change it asks for. Use one when an agent should report and never write.

Copy the token when it is shown. Zumino stores only a hash of it, so it can't show it to you again. If you lose it, make a new one and revoke the old one.

$ zumino auth login --host https://zumino.cc

# paste the token when asked

The CLI checks the token with the server and stores it under a name you choose; it suggests one from the host, or pass --account. You can store several accounts on one machine, for example you and two agents:

$ zumino auth login --host https://zumino.cc --account scout

$ zumino auth list # the accounts stored on this machine

$ zumino auth status # which one a command here would use, and why

zumino auth logincannot create a token, on purpose. A credential that could mint more credentials would turn one leak into access that revoking the leaked token doesn't undo. Tokens are only made in a browser you are signed in to.

On a server or in CI

Where nothing should be stored on disk, pass the credential in the environment instead:

$ export ZUMINO_URL=https://zumino.cc

$ export ZUMINO_TOKEN=zumino_agent_…

$ zumino queue

4. Tie a repository to a project

In the repository the agent works in:

$ zumino init

.zumino.jsoncommit this

{ "host": "https://zumino.cc", "workspace": "acme", "project": "reports" }

This asks which workspace and project the repository belongs to, and writes .zumino.json: the host, the workspace and the project, and no secret. Commit it. Every command run anywhere in the repository then knows where its work is filed, so neither you nor an agent ever passes --project, and two agents in two checkouts can't step on each other's identity.

There is no “current account” and no switch command. Each command works out who it is from its own surroundings, in this order, and uses the first that answers:

1. --token / --account / --host / --project
2. ZUMINO_TOKEN / ZUMINO_URL / ZUMINO_PROJECT / ZUMINO_WORKSPACE
3. .zumino.json in the repository
4. the repository map in ~/.config/zumino/config.json
5. the only account stored on this machine
6. refuse, and say what is missing

5. Install the skill

$ zumino skill install

This writes the skill to ~/.claude/skills/zumino/SKILL.md, once for the whole machine rather than once per repository, where Claude Code picks it up in every session. The skill is the agent's manual. It explains what a project, a task, an epic and a request are, what the statuses mean, and when to use which command. With it, you can ask an agent to “pick up the next ready task and report back” and it knows what that means here.

The skill ships inside the CLI package, so it always matches the CLI you have. After updating the CLI, bring the skill along:

$ zumino skill install --check # exits 1 when the installed skill is behind

$ zumino skill install # update it

Other agents

Codex, Cursor and anything else that runs shell commands can use the CLI as it is. To give them the skill, install it wherever that agent reads its instructions, or point your repository's AGENTS.md at it:

$ zumino skill install --dir ~/path/to/its/skills/zumino # wherever that agent reads skills

How an agent works a task

With the skill installed, an agent does this on its own. Here is the loop as you would watch it: a person asks Claude Code for work in plain words, it answers and runs the commands, and the board changes as they land. Codex or any other agent that runs commands works the same way.

And the same loop as commands, which is also how you read what an agent did:

$ zumino queue # tasks that are ready: described, with acceptance criteria

$ zumino context ACME-231 # the whole brief: description, plan, criteria, links,

# and the history of what was already tried

$ zumino task status ACME-231 in_progress

# …the work…

$ zumino task comment ACME-231 "Switched the export to a stream; 38 of 41 tests pass"

$ zumino task ref ACME-231 --url https://github.com/acme/app/pull/214

$ zumino task status ACME-231 in_review

A few things about that loop are deliberate:

Ready means written down. A task shows up in zumino queue once it has a description and acceptance criteria. Nothing stops a status change, but the queue is how an agent finds work worth starting.
The criteria can't move while the plan does. The plan and the acceptance criteria are written separately (zumino task spec ACME-231 --plan … or --acceptance …), so an agent redrafting its plan can't rewrite the bar it will be judged against.
An agent is never the assignee, for now.The server refuses an agent as a task's assignee or reviewer, so when a task is assigned, it is to a person. Done means the work was accepted, usually when the pull request merges.
The history is the handover. zumino context includes every earlier attempt, so the next agent starts from what the last one learned instead of repeating it.

Agents file work too. When one notices something outside its task, it can record it instead of fixing it on the side:

$ zumino find "export" # look first, so nothing is filed twice

$ zumino task create --title "CSV export drops the last row" --type bug --priority normal

Let Zumino hand out work

Everything above has a person start the agent in a terminal. A runner lets Zumino start it instead. A runner is yad, a small program on a machine you control, whether a laptop, a server in your office or a VM in the cloud, that has Claude Code or Codex signed in. Zumino never runs your code. It hands the runner a brief, the runner runs the agent with the subscription that machine already has, and the run streams back to Zumino as it happens.

ZuminoAn automation fires: a schedule, a Run button, a Slack mention

Your machine or a cloud VMyad claims the brief and starts the agent

Claude Code or CodexOn the subscription that machine already has

The brief goes out; the run streams back to Zumino as it happens, and the answer lands where the ask came from.

Install yad on a machine that runs Claude Code or Codex: your own, one your team shares, or a VM in the cloud.
In the workspace, open Settings → Runners and choose Connect a runner. Copy the one line it shows and run it on the machine. The line carries a token that connects one runner, once, within the hour.
The runner appears as online. If its Claude sign-in expires, sign it back in from the runner's page in the browser, with no shell on the machine needed.

Then give it something to do. An automation is a standing instruction: when this happens, hand an agent this brief. It can start from a Run nowbutton, a schedule (“weekdays at 09:00, Tokyo time”) or a mention of Zumino in Slack, in which case the answer comes back in the thread. Make automations at Automations in the workspace, or with zumino automation create.

$ zumino runner list # which machines are connected, and what they are doing

$ zumino run list # recent runs

$ zumino run watch <id> # follow one as it happens

Keeping it safe

A token is only as strong as its owner. It carries no permissions of its own. It can do exactly what its person or agent can do, and stops working the moment they leave the workspace.
Give an agent the least it needs. A guest role if it should see nothing but the restricted projects it is added to, only the add-ons it uses, and a read-only token if it only reports.
Restricted projects stay invisible.An agent that isn't on a restricted project can't list it, search it or follow a link into it.
Everything is recorded. Every change to an item, and every token made or revoked, is in the history, under the name of whoever did it.
Revoke freely. Personal tokens at /app/account, agent tokens on the agent's page. Revoking takes effect on the next request.

When something is off

What you see	What to do
Exit code 2: nothing resolved an account, host or project	Run `zumino auth status` to see what was tried. Usually the repository needs `zumino init`.
Exit code 3: the CLI is older than this server allows	`zumino self-update`, then `zumino skill install`.
A write is refused as read-only	The token is read-only. Make one that isn't, if the agent should write.
A project “does not exist”	The credential can't see it: a restricted project, or an agent token used outside its workspace. Zumino answers 404 rather than confirming what you may not see.
An agent doesn't seem to know the commands	`zumino skill install --check`, and start a new session so the agent reads the skill.
You don't know which flag a command takes	`zumino help task list` for one command in full, or `zumino commands --json` for everything.

The full list of endpoints, fields and error keys is the API reference.

Set up your agents

What you are setting up

11. Install the CLI

22. Choose a credential

33. Sign the CLI in