Zooid｜可自托管的团队协作聊天与 AI Agent 工作台

access：来源确认 · Deploy with `zooid init`, run with `zooid dev`.

project_type：来源确认 · Zooid is an open-source, self-hostable chat app for collaborating with AI agents alongside your team.

# 🪸 Zooid

[![npm](https://img.shields.io/npm/v/zooid?logo=npm&color=cb3837)](https://www.npmjs.com/package/zooid)
[![CI](https://github.com/zooid-ai/zooid/actions/workflows/ci.yml/badge.svg)](https://github.com/zooid-ai/zooid/actions/workflows/ci.yml)
[![license: MIT](https://img.shields.io/github/license/zooid-ai/zooid?color=blue)](./LICENSE)
[![node](https://img.shields.io/node/v/zooid?logo=node.js&logoColor=white)](https://nodejs.org)

> A chat app to collaborate with AI agents, alongside the rest of your team. Open-source, self-hostable, any model, any CLI.

Zooid is an open-source, self-hostable chat app for collaborating with AI agents alongside your team. It brings [ACP](https://agentclientprotocol.com)-compatible agents (Claude Code, [opencode](https://opencode.ai), Codex, pi, …) into [Matrix](https://matrix.org) rooms as first-class participants — people and agents in the same rooms, threads, and approvals, no separate "AI dashboard," no vendor lock-in. Deploy with `zooid init`, run with `zooid dev`.

**Full docs: [zooid.dev/docs](https://zooid.dev/docs)** · **Join the community server: [community.zoon.eco](https://community.zoon.eco)**

- **Protocol-first.** Matrix for transport (E2E encryption, federation), ACP for the agent contract. Pre-built images for Claude Code, opencode, Codex, and pi; any other ACP-compatible harness (GitHub Copilot CLI, Cursor CLI, Gemini CLI, or your own) connects too.
- **Run it anywhere.** Each daemon is a *workstation* with its own identity, running as many agents as you like — put it on your laptop, a box, a pod, or a cluster; it doesn't have to live next to the homeserver. Several workstations can share one homeserver.
- **Containerized runtime.** Docker or Podman. Each agent runs in its own long-lived container with mounts, env, and capabilities declared in `zooid.yaml`.
- **Multi-agent collaboration.** Agents are standard Matrix users, so an architect bot can `@`-mention a reviewer bot to delegate.
- **Workforce as code.** Declare agents declaratively; review team-structure changes in pull requests, not a web UI.
- **Push or pull.** Pick how the daemon and server connect. *Push* suits a cloud deployment running many agents at high throughput — the server pushes messages straight to the daemon, which advertises a URL. *Pull* has the daemon fetch them itself, nothing to expose — so it runs behind a firewall or on your laptop and catches up on whatever it missed while off.

## Quickstart

Install the CLI:

```bash
npm install -g zooid
```

Run `zooid help` (or `zooid <command> --help`) at any time for the full list of commands and options.

Scaffold a workforce:

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

`zooid init` asks which harness (`claude`, `codex`, `opencode`, `pi`), which model provider, and how to authenticate. It writes a clean `zooid.yaml` and any `.env` it needs.

Every preset can run off a subscription you already have instead of a fresh API key.

Boot the local stack:

```bash
zooid dev
```

> **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`.

`zooid dev` starts a Tuwunel Matrix homeserver in a container, generates the Application Service registration, registers an `admin:admin` user, runs the daemon, and serves the [Zooid web client](https://github.com/zooid-ai/clients). The client's runtime settings come from a generated `/config.json`; its `workforce_space` field is the `matrix.space` alias localpart from `zooid.yaml` (default `dev`). A static deployment sets `workforce_space` in the `config.json` it serves beside the bundle — there is no build-time variable.

Open `http://localhost:5173`, log in as `admin` / `admin`, join `#welcome`, and `@`-mention your agent.

For deployment recipes, the `zooid.yaml` reference, and a deeper tour of how the runtime works, see **[zooid.dev/docs](https://zooid.dev/docs)**.

## Workstations & transport modes

A Zooid daemon is a **workstation** — set a top-level `workstation:` in `zooid.yaml` and its agents get an exclusive `@{workstation}.{agent}:server` namespace. Several workstations (a box, your laptop, a teammate's) can connect to a single homeserver, each owning its own agents.

How a workstation connects is set per-transport with `mode:` — the two choices (push/pull above), named by the value you put in the YAML:

- **`appservice` (push)** — the homeserver delivers events to the daemon, so the daemon advertises an address the homeserver can reach: `port` (default `9099`) when they share a host or network, or an `advertise_url` when the daemon lives on a separate machine, pod, or cluster. Best for cloud deployments running many agents; this is what `zooid dev` uses.
- **`client` (pull)** — the daemon fetches events itself, one outbound sync per agent, with nothing to expose. Runs behind a firewall or on your laptop against a remote homeserver, and catches up on whatever it missed after sleep or restart.

```yaml
workstation: my-laptop
runtime: local
transports:
  matrix:
    homeserver: https://your-homeserver.example
    mode: client
```

Acting (sending, joining) is identical in both modes — only how the daemon ingests events differs.

### Agent isolation

Under `runtime: docker` / `runtime: podman`, each agent gets its own context socket, mounted only into its own container, so one agent cannot read another's rooms even if it learns their session ID.

Under `runtime: local`, every agent runs as your user on your filesystem and can read any other agent's files directly. **`runtime: local` is a single trust domain** — treat every agent in a local workforce as having the access of the most privileged one. Use a container runtime when agents differ in what they should reach.

## The stack

Every layer is open and replaceable.

| Layer          | Project          | License       | Backing                                           |
| -------------- | ---------------- | ------------- | ------------------------------------------------- |
| Agent protocol | **ACP**          | Open standard | Backed by Zed and JetBrains                       |
| Bridge         | **Zooid daemon** | MIT           | This project — the ACP–Matrix bridge              |
| Server         | **Matrix**       | Open standard | Any homeserver — adopted by Germany, France, NATO |
| Client         | **Zooid web**    | MIT           | Built on `matrix-js-sdk` (Apache-2.0)             |

`zooid dev` runs [Tuwunel](https://github.com/matrix-construct/tuwunel) (Apache-2.0, in production at the Swiss government) as the local homeserver, but Zooid points at any Matrix homeserver you already run.

## Agent images

Zooid publishes a small set of base images on GHCR. Drop one into `zooid.yaml` under `container.image` and you're done:

- `ghcr.io/zooid-ai/agent-base` — `node:22-slim` + git. The substrate.
- `ghcr.io/zooid-ai/agent-claude-code` — agent-base + the Claude Code ACP shim.
- `ghcr.io/zooid-ai/agent-codex` — agent-base + the Codex ACP shim.
- `ghcr.io/zooid-ai/agent-opencode` — agent-base + opencode.
- `ghcr.io/zooid-ai/agent-pi` — agent-base + pi + pi-acp.

Pi does not expose MCP servers. When a Pi agent starts, Zooid installs its
native extension at `~/.pi/agent/extensions/zooid-tasks.js`; it gives the agent
the `zooid_*` room-reading and task tools while preserving any operator-owned
extensions already in that directory.

The persona — `CLAUDE.md` / `AGENTS.md`, `.claude/settings.json`, skills, MCP servers — lives in the agent's `workdir` on the host. Zooid bind-mounts that directory into the container at runtime, so the shim picks it up the same way it would on your laptop. No `docker build`, no custom image, no rebuild when you tweak instructions.

## Development

```bash
pnpm install
pnpm -r build
pnpm -r test
pnpm -r typecheck
```

## License

[MIT](./LICENSE)

Node.js 环境与 npm（README 徽章标注 node 版本，正文未展开）；全局安装 zooid CLI；本地快速开始需安装并运行 Docker 或 Podman；zooid init 需选择模型提供方与认证方式，可使用已有订阅或 API Key，具体模型与费用待核验；生产部署需可用的 Matrix homeserver 或使用内置 Tuwunel；Web 客户端为独立仓库，默认本地地址 http://localhost:5173。