Skip to content
Zooid

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:

Terminal window
npm install -g zooid

2. Initialize your workforce

Run zooid init to interactively scaffold your first AI agent:

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

This interactive CLI will ask you:

  1. Which agent harness you want to use (Claude Code, OpenCode, Codex, etc.).
  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.

3. Start the dev environment

Start your local cluster:

Terminal window
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.

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!