zooid.yaml

The zooid.yaml file is the declarative manifest for your Zooid daemon [ZOD033]. It defines the runtime that wraps each agent’s ACP shim, the transports that connect the workforce to the outside world, and the agents themselves.

This page orients you with annotated examples. For the authoritative field-by-field reference, see the generated API pages — they are emitted directly from the TypeScript types the daemon parses, so they cannot drift from the implementation.

Shape at a glance

runtime: podman           # local | docker | podman
container:                # optional workforce-wide container defaults (no env)
  image: node:20

transports:               # at least one entry, keyed by an operator-chosen name
  matrix:
    homeserver: http://localhost:8448

agents:                   # at least one entry, keyed by the agent's name
  assistant:
    acp:
      preset: opencode
    matrix:
      rooms:
        - '#general'

See ZooidConfig for every top-level field.

Transports

The transports: block lets the daemon expose multiple endpoints or connect to multiple servers at once. Each entry is discriminated by type.

Matrix transport

The Matrix transport runs as an Application Service and impersonates each agent’s user via ?user_id=. Most fields (type, sender_localpart, user_namespace, as_token, hs_token) default sensibly [ZOD048]:

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

Full field list: MatrixTransportConfig.

HTTP transport

A plain HTTP API transport for webhook-driven setups:

transports:
  my-http:
    type: http
    port: 3000

Full field list: HttpTransportConfig.

Agents

Each entry under agents: declares one agent. transport, matrix_user_id, and workdir default from the agent key when omitted [ZOD048]:

agents:
  assistant:
    acp:
      preset: opencode
    matrix:
      user_id: '@assistant'             # shorthand for @assistant:your-server
      display_name: 'Code Assistant'    # optional: human-readable name
      rooms:
        - '#general'                    # shorthand for #general:your-server

Full field list: AgentConfig.

Identifiers and Implicit Servers

Inside zooid.yaml, you can omit the homeserver suffix from user IDs and room aliases [ZOD047]. The daemon automatically infers the correct server from your transport’s user_namespace. For example, @docs resolves to @docs:localhost (or whatever your configured server is). This keeps the YAML terse and reduces errors.

Display Names

You can provide an optional display_name field for each agent under the matrix: block [ZOD047]. This sets the human-readable name written to the agent’s Matrix profile, causing the agent to render nicely in the Zooid web client (“Code Assistant” instead of @assistant). If omitted, it falls back to the user ID’s localpart.

The acp: block

acp: is an XOR — either a registered preset or an explicit command:

acp:
  preset: claude          # claude, codex, opencode, cline, kiro, gemini

acp:
  command: node
  args: ['./my-custom-acp-shim.js']

Full shape: AcpAgentSpec.

Environment variables

Zooid expands ${VAR} references in your YAML against the daemon’s process.env (and an adjacent .env). For security, env vars are never forwarded into agent containers automatically — list them explicitly under container.env:

agents:
  assistant:
    container:
      image: 'node:20'
      env:
        ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}

ZOOID_* keys and ${ZOOID_*} references are rejected. See ContainerConfig for the full field list.

Mounts

The agent’s workdir is auto-mounted into its container. To expose additional host paths (e.g. a source repo the agent needs to read), declare them under container.mounts:

agents:
  assistant:
    container:
      mounts:
        - source: /host/path/to/repo
          target: /workspace/repo
          readonly: true

Full shape: AcpMount.