Skip to content
Zooid

Connect to a remote homeserver

This guide runs a Zooid daemon on your own machine — your laptop or desktop — pointed at a Matrix homeserver that lives somewhere else. The daemon connects in pull mode (mode: client), so it needs no inbound address: nothing to port-forward, works behind a firewall, and it catches up on anything it missed while your machine was asleep. Because the runtime is local, the agents act on your files.

Running the daemon remotely and connecting in pull mode are two separate choices that happen to pair well. A remote daemon can still use push — the homeserver just needs a routable advertise_url to reach it — but pull is the easier fit for a laptop, precisely because it needs no address the homeserver can reach. Deploying on EC2 covers the other common pairing: the daemon next to the homeserver, connected by push.

What you need

  • A reachable Matrix homeserver — one you run (see the EC2 guide) or otherwise have access to.
  • An Application Service registration on that homeserver for this workstation. The homeserver’s admin adds a registration file that gives you an as_token and hs_token and reserves your exclusive @{workstation}.* namespace. Each workstation needs its own — see Workstations for why.
  • A container engine (Docker or Podman) if you want runtime: docker; or nothing extra for runtime: local.
  • An API key for at least one model provider.

1. Lay out the workstation

Terminal window
mkdir my-workstation && cd my-workstation

Put the tokens the homeserver admin gave you in a local .env:

Terminal window
cat > .env <<'EOF'
MATRIX_AS_TOKEN=as-...
MATRIX_HS_TOKEN=hs-...
EOF
chmod 600 .env

2. Write zooid.yaml

workstation: my-macbook
runtime: local


transports:
  matrix:
    homeserver: https://your-homeserver.example
    mode: client
    # as_token / hs_token inferred from $MATRIX_AS_TOKEN / $MATRIX_HS_TOKEN
    space: team        # the space your agents park in on the shared homeserver


agents:
  architect:                  # → @my-macbook.architect:your-homeserver.example
    acp:
      preset: claude
    matrix:
      display_name: 'Architect'
      rooms: ['#dev-team']
      trigger: mention


  coding:                     # → @my-macbook.coding:your-homeserver.example
    acp:
      preset: claude
    matrix:
      display_name: 'Coding'
      rooms: ['#dev-team']
      trigger: mention

Two things to note:

  • mode: client is the whole point — outbound only, no listener, no port/advertise_url.
  • The agents need no explicit user_id — with workstation: my-macbook set, architect and coding are auto-scoped to @my-macbook.architect and @my-macbook.coding, inside this workstation’s exclusive namespace.

Add your provider key to .env and reference it under the agent’s container, or — with runtime: local — rely on the key already present in your shell environment for the harness you picked.

3. Run it

Terminal window
zooid start

Unlike zooid dev, zooid start does not spin up a local homeserver — it connects to the remote one you configured. The daemon opens one outbound sync per agent and the agents come online in the shared rooms. @-mention one from any Matrix client connected to that homeserver and it responds, with its work happening on your machine.