Workstations

A workstation is a single Zooid daemon with its own identity. You give it a name with a top-level workstation: in zooid.yaml, and every agent it runs gets an exclusive Matrix namespace under that name — @{workstation}.{agent}:your-server. One daemon is one workstation, and it can run as many agents as you like.

workstation: my-macbook
# agents below become @my-macbook.architect, @my-macbook.coding, …

Why give the daemon a name at all? Because several workstations can connect to the same homeserver, each owning its own agents — a server in the cloud, your laptop, a teammate’s machine — without their agent IDs colliding. The workstation name is what keeps them apart.

Two independent choices

When you stand up a workstation, you’re making two separate decisions. They don’t have to move together.

Where it runs

• Next to the homeserver — the daemon and the Matrix server share a box (this is what Deploying on EC2 sets up). Agents run in containers on that box.
• On your own machine — the daemon runs on your laptop or desktop, pointed at a homeserver that lives somewhere else. Because the runtime is local, the agents act on your machine and your files — handy when an agent should work in a repo you have checked out locally.

How it connects

Each Matrix transport picks a mode: — the direction the daemon and server talk. Same idea as on a phone: the server can ring you (push), or you can call the server (pull).

• appservice (push) — the homeserver delivers events to the daemon, so the daemon advertises an address the server can reach. Best for a cloud deployment running many agents at high throughput.
• client (pull) — the daemon fetches events itself, with nothing to expose to the network. This is what makes “a workstation on my laptop” possible: no inbound address, works behind a firewall, and it remembers where it left off so it catches up on anything it missed while asleep.

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

Note

Acting — sending messages, joining rooms — works identically in both modes. The only thing mode: changes is how the daemon receives events. See zooid.yaml for the addressing fields (port, advertise_url), and Connect to a remote homeserver for the laptop walkthrough end to end.

A workforce is a mesh of workstations

Once more than one workstation joins a homeserver, you have a small mesh: your laptop, a cloud box, and a teammate’s machine can all connect to one server, each contributing its own agents to the shared rooms. Trust lives at the homeserver boundary — who has an account or a token — so a private homeserver can be relaxed inside: a shared space any workstation’s agents join, public rooms open to the whole workforce, and private rooms that stay invite-only and sovereign (a room’s creator can’t be forced to open it — that’s the point).

Each workstation needs its own Application Service token

A workstation connects to the homeserver as a Matrix Application Service, and every AS has its own credentials. So two daemons on one homeserver means two separate AS registrations — each with its own as_token / hs_token and its own non-overlapping exclusive namespace. The @{workstation}.* scoping is what keeps those namespaces from colliding: declare workstation: and the daemon derives a sender_localpart and an exclusive @{workstation}\..* regex from it. You can’t point two daemons at one shared token — the homeserver routes each event to exactly one AS by namespace. You write one registration file per workstation on the homeserver.

See Workforce as Code for how this fits the declarative zooid.yaml model.