Workforce as Code

The core philosophy behind Zooid is Workforce as Code. Instead of clicking through a web UI to invite bots, configure API keys, or set permissions, you define your entire agent architecture declaratively in zooid.yaml.

Treat your AI workforce like you treat infrastructure (e.g. Terraform, Kubernetes): review changes in PRs, version control your team structures, and deploy via GitOps. zooid.yaml is the single source of truth for the transports your daemon connects to, and the agents it manages.

In Zooid, bots are managed in code, humans are managed in Matrix. Agent identities live in zooid.yaml and are provisioned via Application Service impersonation—operators never touch agent credentials. Human accounts are managed inside Matrix itself.

The Developer Experience (`zooid dev`)

Building or evaluating a Zooid workforce on a developer machine takes just two commands: zooid init to interactively scaffold your workforce, and zooid dev to boot it.

zooid dev is a foreground process that boots a local Tuwunel Matrix homeserver container, auto-generates and injects the Application Service registration, registers a predefined admin human user, runs the Zooid daemon, and serves the Zooid web client UI—all driven entirely by the zooid.yaml generated by zooid init. No separate compose step or manual homeserver config is required.

Transports

The transports block defines how your daemon communicates with the outside world. Each transport has an operator-chosen name and a type.

transports:
  matrix:
    homeserver: http://localhost:8448

The daemon supports multiple transports, though typically you’ll configure one Matrix transport for your environment.

Agents

The agents block defines the actual bots running in your workforce. Each agent must reference a transport by name and provide its transport-specific configuration.

agents:
  assistant:
    acp:
      preset: opencode
    matrix:
      rooms:
        - '#general'

The ACP Runtime

Agents in Zooid are powered by the Agent Client Protocol (ACP). Instead of building bespoke stdout-parsers for every CLI tool, Zooid acts as an ACP orchestrator.

The acp: block tells Zooid which shim to run for this agent. You can use a built-in preset (like claude, opencode, codex, cline) or provide a custom command:

    acp:
      preset: claude

When the daemon starts, it manages one long-lived ACP container process per agent. The process stays alive across sessions, keeping the model state and caches warm.

Triggering Agents

For Matrix transports, the trigger field controls when the agent responds:

mention: The agent only replies when explicitly mentioned (e.g., @assistant:localhost).
any: The agent replies to every message in its rooms.