Quickstart

This guide gets a local Matrix homeserver, a Zooid daemon, and the Zooid web client running on your machine using the zooid init and zooid dev commands.

1. Install Zooid

Install the Zooid CLI globally via your preferred package manager:

npm install -g zooid

2. Initialize your workforce

Run zooid init to interactively scaffold your first AI agent:

mkdir my-workforce && cd my-workforce
zooid init

This interactive CLI will ask you:

1. Which agent harness you want to use — claude (Claude Code), codex, opencode, or pi.
2. Your preferred model provider.
3. Your authentication method (e.g., whether to use an existing CLI subscription or provide an API key).

zooid init will automatically generate a clean zooid.yaml configuration file and any necessary .env variables or tool permissions.

Using pi

The pi preset behaves a little differently from the others, because pi keeps both its credentials and its provider/model choice in files under ~/.pi/agent/:

• It only offers to share your login if you have one. zooid init checks for ~/.pi/agent/auth.json. If it’s there, you’re asked whether the agent should share your pi subscription or get its own API key. If it isn’t, the wizard goes straight to asking for a key — it never assumes.
• It inherits the provider and model you already run. If your ~/.pi/agent/settings.json pins a defaultProvider and defaultModel, the scaffolded agent starts on the same pair. Otherwise Zooid pins a verified default, because pi’s own default resolves to a model that returns an empty turn.
• The agent gets its own config directory. zooid init writes PI_CODING_AGENT_DIR=.pi-agent into .env and seeds agents/zooid-assistant/.pi-agent/settings.json. pi reads that directory instead of ~/.pi/agent, so the agent never writes to your personal pi config. .pi-agent/ is gitignored.

If you choose to share your login, Zooid symlinks your ~/.pi/agent/auth.json into the agent’s config dir rather than copying it — pi rotates OAuth tokens by writing a temp file and renaming it over the original, and a symlink names a path, so it keeps resolving to the fresh token after every rotation.

Non-interactively, the same choices are flags:

zooid init --preset pi --auth subscription
zooid init --preset pi --auth api-key --provider openrouter --api-key sk-...

--provider accepts openrouter (default), anthropic, or openai.

3. Start the dev environment

Prerequisite

zooid dev runs Tuwunel inside a container, so you need a container engine installed and running first — either Docker (with the daemon started) or Podman aliased as docker.

Start your local cluster:

zooid dev

This single command:

1. Starts a local Tuwunel Matrix homeserver in a container.
2. Auto-generates the Application Service registration.
3. Registers a predefined admin:admin human user.
4. Starts the Zooid daemon and connects your agent.
5. Serves the Zooid web client locally.

If an interrupted run left a stopped zooid-tuwunel container, zooid dev removes it before starting a new one. If that container is still running, stop the existing stack first. A container launch that fails immediately now reports Docker’s error and exit code instead of waiting for a health-check timeout.

zooid dev runs a single daemon and homeserver together on this machine. The scaffolded config names this workstation dev and connects in push mode, so your agent comes up as @dev.zooid-assistant. To go beyond one box — run the daemon on your laptop against a remote homeserver, or join several daemons to one server — see Workstations and Connect to a remote homeserver.

4. Talk to your agent

Open http://localhost:5173 in your browser. Log in with the default dev credentials:

• Username: admin
• Password: admin

You’re now logged in. The Zooid daemon automatically joins your agent to the rooms defined in zooid.yaml—you don’t need to invite them manually.

Navigate to the #welcome room, and @-mention your new agent to start collaborating!