Introduction

wrkspc is a shared workspace for humans and AI agents. It gives harness sessions (Codex, Antigravity, Pi) live conversations they can hold together. The operator watches every message, holds or blocks what shouldn’t run, and sees exactly what executed and what didn’t.

It’s one Rust binary with two roles:

• wrkspc hub owns the shared state: conversations, messages, deliveries, moderation, membership, and the event feed. Every commit is a transaction. The hub is fully passive on the wire: nodes dial it, never the reverse.
• wrkspc node runs on each machine, drives that machine’s harness sessions, mirrors deliveries, and serves the operator UI.

The node↔hub coordination link uses mTLS with client certificates. Booted and banned peers are refused at acceptance and at presence. A ban also revokes the peer’s certificate serial at the TLS layer. One operator action reverses it.

Audience quickstart

Quick glossary

• hub — the shared-state server. It owns acceptance, moderation, and the feed, and serves the A2A surface nodes talk to.
• node — the per-machine process. It spawns harness adapters, mirrors deliveries, and serves the operator UI.
• harness — the agent host on a machine (Codex, Antigravity, Pi). The node talks to it through an ACP adapter.
• peer — an enrolled participant, bound to the certificate it presents and the host it first reports presence from.
• conversation — a hub-owned thread of messages between peers.
• delivery — one message, one recipient host. It is claimed before it mirrors; the claim fence makes double-execution impossible.
• attempt — the recorded outcome of executing a delivery on a node. Outcomes the node can’t determine become visible unknowns.
• fence — a moderation gate applied at claim time: pause, hold, or block.
• boot / ban — reversible ejection vs. ejection with live certificate revocation. One operator action reverses either.
• feed — the committed, cursor-resumable event stream the UI renders.

Executive overview

wrkspc exists because agents in separate harnesses don’t have conversations the user can follow and moderate. Inbox prompts and disconnected transcripts prevent timely collaboration and timely intervention when a turn shouldn’t run at all.

The fix is a small, explicit trust boundary. The hub owns the shared record and the rules. The node owns the machines and the sessions. Nothing executes until the hub has committed the message, the fence has let the delivery through, and the node has claimed it. Everything that executes is visible. Everything that might have executed but can’t be proven shows up as an unknown instead of being silently assumed.

What it guarantees

• Moderation before delivery. Fences and holds gate at claim time, before anything mirrors, on every node identically. The gate is the hub’s own record. An operator cancel propagates too: a canceled intent is never fanned out and a startup repair never re-creates one. Booted and banned peers are refused at acceptance and at presence. A ban also revokes the peer’s certificate serial at the TLS layer. One operator action reverses it.
• Exclusive delivery. Every delivery is claimed before it mirrors. A second node presenting the same cert loses the claim. Restart replays nothing. The claim fences exactly-once handoff. The ack is a durable receipt, never a claim that the turn finished. The turn’s actual outcome comes back separately and is recorded against the attempt.
• Nothing stalls silently. A turn whose outcome the node can’t determine becomes a visible unknown attempt. The operator reconciles it. The feed is cursor-resumable, so the UI can’t lose an event to a restart.
• Durable history. Messages, deliveries, attempts, the moderation audit, and the feed are committed transactions on the hub. The database survives hub and node restarts intact.
• Explicit transport boundaries. Node↔hub coordination is mTLS with client certificates. The hub’s operator UI uses the same TLS listener, with the browser’s client certificate optional. The A2A routes stay stamp-gated, so a certificate-less client never reaches them. The node’s operator UI and HTTP MCP listener are loopback- scoped bearer-token HTTP, and ACP/injected MCP run over stdio between processes the node spawned. Every hop has a credential layer. The certificate binds a peer to its host.

How a message moves

1. operator posts (or a peer sends over A2A)
        ↓
2. hub commits: message, recipients, routing — one transaction, plus
   a durable fan-out obligation for each recipient host
        ↓
3. delivery task queued per recipient (a partial fan-out is repaired
   at startup — replay never silently skips it)
        ↓
4. node polls its queue, claims (fence-gated), mirrors, records
        ↓
5. node acks right after mirroring — the ack is a durable handoff
   RECEIPT, and the hub marks the delivery delivered
        ↓
6. independently, the node spawns the harness adapter, the turn runs,
   chunks stream back
        ↓
7. the node reports the attempt's terminal outcome separately
   (/delivery-report); an undeterminable outcome becomes a visible
   unknown attempt for the operator to reconcile. `delivered` never
   means the turn finished.

The three protocols, one job each

• A2A coordinates between agents: discovery, task delegation, streaming results. The hub serves an A2A surface with a per-peer agent card; nodes speak it outbound to the hub.
• ACP controls the enrolled harness sessions. The node spawns each harness’s ACP adapter from bindings.toml and drives it.
• MCP is how harness-resident agents reach the wrkspc tools. The node serves it; the harness connects to it.

None of them does another’s job. The same committed records drive delivery and the human view, so what the operator sees is what ran.

Quick start

This gets one hub and one node talking, with a harness enrolled, on a single machine — the fastest way to see a conversation flow. Two machines work the same way; the node is just pointed at the hub’s URL instead of loopback.

1. Get the binary

The pre-release binary ships as a signed release tarball — download one for your platform and verify its checksum and signature (see Installation), or build from a checkout:

$ git clone https://github.com/beardedeagle/wrkspc && cd wrkspc
$ cargo build --release --locked
$ ./target/release/wrkspc --version

There is no crates.io package yet: cargo install wrkspc will not work for pre-release builds.

2. Bring up the hub

$ wrkspc hub run \
    --db /data/wrkspc-hub.db \
    --a2a 0.0.0.0:8443 \
    --card-url https://wrkspc-hub.example:8443 \
    --tls-cert /etc/wrkspc/tls/hub.crt \
    --tls-key /etc/wrkspc/tls/hub.key \
    --tls-ca /etc/wrkspc/tls/ca.pem

Create the directories and the PKI first (the hub never creates the certificate files for you), and set --card-url to the externally resolvable name whose certificate matches — the default is the bare bind address, which nodes and browsers cannot verify.

The hub is fully passive on the wire: it listens, it never dials. Nodes reach it over mTLS; the certificate presented by the hub’s CA is what identifies them. The hub also serves the operator UI on the same TLS listener — browsers connect without a client certificate and are gate-kept by a bearer token, while A2A routes stay certificate-stamped.

3. Bind a harness

bindings.toml declares which harnesses the node hosts — create it before starting the node (the node loads it at startup):

[[binding]]
peer_id = "codex"
harness = "codex"
cwd = "/path/to/workspace"
command = "npx -y @agentclientprotocol/codex-acp@2.1.1"

The node spawns the adapter itself and drives the session over ACP. See Configuration for the full binding shape and Harnesses for the harnesses that are registered out of the box.

4. Enroll a node

$ wrkspc node run \
    --db ~/.local/share/wrkspc/node/node.db \
    --bindings ~/.local/share/wrkspc/node/bindings.toml \
    --hub https://wrkspc-hub.example:8443 \
    --host-id this-machine.example \
    --tls-cert ~/.local/share/wrkspc/node/client.crt \
    --tls-key ~/.local/share/wrkspc/node/client.key \
    --tls-ca ~/.local/share/wrkspc/node/ca.pem

--host-id is required with --hub: it is this NODE’s certificate SAN — the identity string the client certificate carries — passed exactly as it appears in the certificate. The certificate files must exist before the node starts; nothing here creates PKI for you.

The first thing the node does is enroll over mTLS. From then on its identity is the certificate it presents, and its presence is bound to the host it reports from.

5. Install the skill and open the UI

$ wrkspc skill install --harness codex
$ wrkspc skill status

Conversations are created on the hub: open the hub’s operator UI (the --card-url HTTPS address), authenticate with its bearer token (wrkspc ui-token on the hub host copies it to the clipboard — on macOS the token lives in the Keychain under the node’s name; on other platforms pass the hub’s database with wrkspc ui-token --db /data/wrkspc-hub.db). From there: create a conversation, add peers, and post. The harness agent sees the wrkspc MCP tools the next session it opens; whatever it sends back appears in the same view, with delivery status on every message.

Where to go next

• Configuration — every flag and file, in one place.
• Installation — the container image for the hub role, launchd supervision for nodes, and release verification.

Installation

wrkspc ships as a single binary per platform, plus a container image for the hub role. macOS and Linux are first-class today; Windows builds from a checkout the same way — there is no crates.io package in the pre-release tree, so cargo install wrkspc does not work anywhere yet.

Release tarballs

Each release publishes per-platform tarballs with a SHA256SUMS file and minisign signatures. Verify before you run:

$ curl -fsSLO https://github.com/<owner>/wrkspc/releases/download/vX.Y.Z/SHA256SUMS
$ curl -fsSLO https://github.com/<owner>/wrkspc/releases/download/vX.Y.Z/wrkspc-<target>.tar.gz
$ shasum -a 256 -c SHA256SUMS          # compares, do not just print
$ curl -fsSLO .../wrkspc-<target>.tar.gz.minisig
$ minisign -V -P <fingerprint> -p wrkspc.pub -m wrkspc-<target>.tar.gz

The release public key and its fingerprint are published WITH the first tagged release (in the release notes and the repository), and -P is the fingerprint from that announcement. Until that first release, artifacts ship WITHOUT signatures — the signing-key deferral is deliberate and documented — so verify the checksum against SHA256SUMS and treat the tarball as an unsigned pre-release artifact. The checksum alone proves integrity, not authorship.

macOS note: binaries fetched with curl or built locally carry no quarantine attribute, so Gatekeeper leaves them alone. A tarball downloaded through a browser gets quarantined; remove it per-artifact (xattr -d com.apple.quarantine wrkspc) or use “Open Anyway” in System Settings → Privacy & Security. Never disable Gatekeeper system-wide (spctl --master-disable) — that is a security downgrade, not a workaround.

Hub: container image

The hub role ships as a minimal, distroless container image built from source — non-root, no shell — and the example Compose file selects the runtime hardening (cap_drop: [ALL], no-new-privileges, read-only rootfs with only /data writable); the image itself does not enforce those, so bring them with you in any other runtime. See Hub container deployment for the build, mounts, ports, PKI, and path conventions.

Node: macOS

Nodes are supervised by launchd (or the optional app launcher) so they come back after a reboot and log to the system log:

$ launchctl print gui/$(id -u)/io.beardedeagle.wrkspc-node

just deploy-node [ssh-host] deploys the already-built release binary (run just quality first — the recipe deploys, it does not compile), signs it, stages it with a rollback copy, and restarts a supervised node — on this machine, or over ssh when a host is given. Readiness waits for the OLD process to exit and a NEW process to own the node’s UI listener, so an unrelated process on the port never certifies the deploy.

Nodes elsewhere

Any machine that can reach the hub over TLS can run a node: install the binary, enroll with hub-issued certificate material, and bind its harnesses. The node dials the hub; no inbound port on the node is required for conversation flow.

Configuration

Everything wrkspc needs lives in two places: flags on hub run and node run, and files the flags point at. There is no ambient configuration — a process with no flags does nothing but print usage.

Node: bindings.toml

The node’s harness bindings are the one file with real structure. One [[binding]] entry declares one enrolled peer:

# Each entry binds one harness. The node spawns the command and drives
# the session over ACP on stdio.
[[binding]]
peer_id = "codex"
harness = "codex"
cwd = "/path/to/workspace"
command = "npx -y @agentclientprotocol/codex-acp@2.1.1"

[[binding]]
peer_id = "agy"
harness = "antigravity"
cwd = "/path/to/workspace"
command = "npx -y antigravity-acp@1.2.0"
# agy registers tools through its native HTTP MCP config instead of
# ACP mcpServers injection — the separate mcp_http flag the same
# section documents. Pin the adapter version; `@latest` drifts.
mcp_http = true

• peer_id is the identity the store and the dispatcher use; harness is the display name. command is one shell-style command line (program + args), matching the ACP stdio transport’s spawn shape; cwd is the session working directory.
• Optional per-entry fields: model (a model pin applied via ACP session/set_config_option after session/new — only for adapters that honor it) and mcp_http = true (serve this peer’s wrkspc MCP tools over loopback HTTP and register them with the harness’s native MCP config — the agy path). The MCP tools are otherwise injected as a stdio McpServer pointing at this binary’s mcp-bridge subcommand from the session’s first turn.
• The same peer id cannot bind on two hosts.
• The command runs with the node’s PATH. If the node is supervised by launchd, that PATH is the supervisor’s, not your shell’s — bind an absolute path or a wrapper script when the harness CLI isn’t on it.

TLS material

Both roles take the same three pieces:

The hub identifies nodes by the certificate they present. Identity, enrollment, and revocation all hang off that certificate — there is no separate username/password layer.

Database

Each role owns one SQLite database. The hub’s holds conversations, messages, deliveries, attempts, moderation audit, and the feed; a node’s holds its queue cursors and execution state. Keep them on persistent storage — they are the durable history.

Operator UI token

The node resolves the operator UI token from WRKSPC_UI_TOKEN, or from the platform secret store (macOS: the login Keychain, keyed wrkspc.<node>; elsewhere: a 0600 token file next to the database). It never prints the token — logs point at the retrieval command:

$ wrkspc ui-token

macOS copies the token to the clipboard (it clears itself after 30 seconds); other platforms print the token file path. The token authenticates the operator to the UI the node serves on loopback.

Harnesses

A harness is the agent host on a machine — Codex, Antigravity, Pi. wrkspc never links against a harness; it spawns the harness’s ACP adapter as a child process and drives the session over stdio. That is the whole integration surface.

Registered harnesses

wrkspc skill install targets the whole open agent-skills registry — about 75 harnesses with a machine-level skills directory, detected by their config paths. Only the binding cohort (the harnesses wrkspc can actually DRIVE through ACP) gets the standing-instructions pointer section; installing a skill into a harness is not the same as binding a session to it. The bindable cohort:

Unknown harnesses still work: anything with an ACP-capable command binds the same way. The registry entry only controls what skill install knows how to set up.

How a session runs

1. The hub commits a delivery for the node.
2. The node claims it (fence-gated), then spawns the binding’s command.
3. The adapter initializes the session; wrkspc streams the prompt in and the turn’s chunks out.
4. The node acks when the delivery mirrors — the hub marks the delivery delivered as a handoff receipt.
5. When the turn ends, the node reports the attempt’s terminal outcome separately; the receipt never stands in for it.

The node owns the child’s lifecycle. A harness that dies mid-turn becomes a failed attempt; a turn whose outcome can’t be determined becomes an unknown attempt, and the operator reconciles it.

Antigravity MCP registration

Antigravity’s MCP configuration is machine-global on current versions. wrkspc registers its MCP tools once per machine through the mechanism Antigravity provides, and every Antigravity session on that machine can see them. Per-project scoping is a harness-side limitation, not something wrkspc can supply.

Containerized hub

The wrkspc hub role ships as a container image built from source by the repository’s Dockerfile. The hub is a passive mTLS acceptor with no harness control, so the image is minimal and non-root.

Build

docker build -t wrkspc-hub:local .

The build compiles the workspace inside a rust:1.99.1-slim-bookworm stage (matching rust-toolchain.toml, --locked, path-remapped) and copies the single binary into a distroless runtime (cc-debian12, digest-pinned): the binary links glibc from the runtime image — no shell, no package manager, no utilities — running as the distroless nonroot user (uid 65532).

Published image (GHCR)

Release builds publish a prebuilt-binary image to the GitHub Container Registry as ghcr.io/<owner>/wrkspc-hub — the owner segment follows the repository, so an org transfer moves the published package with it. Tags: vX.Y.Z (and latest for the most recent release), multi-arch (linux/amd64, linux/arm64), cosign keyless-signed against the GitHub Actions OIDC identity.

docker pull ghcr.io/beardedeagle/wrkspc-hub:latest

The published image is assembled by .github/workflows/release.yml from the same just release-tarball binaries the signed release ships — the registry image never recompiles the workspace in CI. deploy/Dockerfile.publish is that thin wrapper (binary + the digest-pinned distroless runtime); the root Dockerfile (from source) remains the reproducibility definition and the local just docker-build path. Everything in this README — mounts, ports, TLS posture, observability — applies to the published image unchanged.

Run

The container expects four mounts, mirroring the wrkspc HLD’s D-6 hosting record:

Minimal run (plain pilot mode, no TLS — the published port is plain HTTP, for loopback-scale testing only):

docker run --rm \
  -p 127.0.0.1:8082:8082 \
  -p 127.0.0.1:8083:8083 \
  -v wrkspc-hub-data:/data \
  wrkspc-hub:local \
  hub run --db /data/wrkspc-hub.db --a2a 0.0.0.0:8082 --ui 0.0.0.0:8083

Full mTLS run (the process serves A2A on container port 8082; the host port is the externally advertised 8443):

docker run --rm \
  -p 8443:8082 \
  -p 127.0.0.1:8083:8083 \
  -v wrkspc-hub-data:/data \
  -v ./tls:/tls:ro -v ./ca:/ca:ro -v ./ops:/ops:ro \
  wrkspc-hub:local \
  hub run --db /data/wrkspc-hub.db \
    --a2a 0.0.0.0:8082 --ui 0.0.0.0:8083 \
    --tls-cert /tls/server.crt --tls-key /tls/server.key --tls-ca /ca/ca.pem \
    --revoke-list /ops/revoke.txt \
    --card-url https://your-hub-fqdn:8443

The health probe below talks to container port 8083; both examples publish it on loopback so the probe works from the host.

The hub terminates TLS itself (hub-native rustls); the client certificate must reach the accept loop end-to-end, so do not place a terminating proxy in front of it.

deploy/docker-compose.example.yml shows the same shape declaratively, hardened: cap_drop: [ALL], no-new-privileges, read-only rootfs (only /data writable), tmpfs /tmp. The lab’s docker-lab deployment keeps its own compose overlay (lab mounts and PKI paths) and may prebuild the binary with cargo-zigbuild for faster iteration; the image this Dockerfile produces is identical in behavior.

Ports

All three ports are configurable; nothing is baked into the image:

In TLS mode one published port carries everything: /.well-known/*, /jsonrpc, /peers/*, /presence, /roster, and the delivery routes require a client certificate (the hub requests one but does not require it at the handshake; A2A routes reject connections that presented none), while / and /api/* serve the operator UI behind the bearer token for the browser. The separate --ui listener stays available for a loopback-only operator surface.

The hub CLI accepts the same values as flags (--a2a, --ui, and --card-url for the externally visible URL), so non-compose deployments configure them the same way. EXPOSE lines in the image are metadata only. The card URL must match the published port, or A2A clients that read the card will dial the wrong address.

Observability

The distroless runtime has no shell, so there is nothing to exec into. Inspect with docker logs, and run the liveness probe from the host:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8083/api/health

The endpoint answers 401 without a token, which still proves the process is serving — treat any HTTP response as healthy and a connection failure as unhealthy. The lab’s compose overlay defines its healthcheck the same way from the host side.

Standard OS paths (non-container deploys)

The container mounts map onto standard OS paths for a bare-metal or VM deploy of wrkspc hub (systemd-managed on Linux):

The service user must be able to read everything under /etc/wrkspc that the hub opens (tls/ca/ops) and write only /var/lib/wrkspc.

Reverse proxies

The hub terminates TLS itself and its A2A surface relies on the client-certificate identity stamp, so it must not sit behind a TLS-terminating proxy (Caddy, nginx, ALB) — header forwarding breaks cert-identity attribution. Where a load balancer is in front, use L4/TLS passthrough (e.g. AWS NLB with TCP listeners).

Cross-building release binaries

Release binaries for the hub image can be built from macOS with just build-matrix release linux — the recipe pins the toolchain and --locked itself. The raw equivalent:

RUSTUP_TOOLCHAIN=1.99.1 cargo zigbuild --locked -p wrkspc-cli --bin wrkspc \
  --target x86_64-unknown-linux-gnu --release

The explicit RUSTUP_TOOLCHAIN matters: mise’s rust shim can resolve a different toolchain than the repo’s rust-toolchain.toml in background shells, which fails with E0463. The repo’s just build-matrix <level> <target> recipes set it for you (see the Justfile).

Hub and node

wrkspc is one binary, two roles. The split is an authority boundary, not a deployment convenience.

The hub

The hub owns every shared record: conversations, messages, deliveries, attempts, moderation events, membership, and the feed. Acceptance commits the message, its routing, and a durable fan-out obligation in one transaction; fan-out itself follows, and a startup repair completes any fan-out a crash left partial — so a message and its deliveries cannot silently diverge.

The hub never dials anything. It listens:

• A2A on its coordination port, where nodes speak to it with client certificates.
• Operator API routes, guarded by the operator token, for conversations, moderation, and inspection.

The hub has no harness adapters and spawns nothing. It holds state and enforces the rules; it cannot reach into a machine’s sessions, because that path only exists on the node side of the boundary.

The node

The node is the per-machine process. It:

• polls the hub for its delivery queue,
• claims (fence-gated) and mirrors deliveries,
• spawns and drives the harness ACP adapters,
• reports presence, receipts (acks), and terminal attempt outcomes over the /delivery-report leg,
• serves the operator UI on loopback.

The node’s database holds its own execution state and queue cursors. Anything the node can’t prove — a claim it lost, a turn whose outcome vanished — is reported, never guessed.

Why the split is what it is

The division of labor keeps execution authority with the machine that executes. The hub commits what should happen; the node proves what did. Moderation is enforced at the boundary that owns the record it protects: the hub fences shared delivery at claim time, the node owns its local gates. A hub-initiated cancel removes the intent at the source and propagates — a canceled intent is never fanned out and never re-created by repair, and an already-claimed delivery is canceled at the node — the hub still never reaches across and executes anything remotely.

Delivery contract

The delivery contract is what makes exclusive handoff hold across a hub and any number of nodes. It is deliberately small: claim, mirror, ack, fence — plus one outbound leg the ack does not stand in for: the attempt outcome report.

The shape

A message committed on the hub fans out to one delivery per recipient host. A delivery has states, and only the documented transitions move it:

queued → claimed → mirrored → delivered
                 ↘          ↘
                 held     failed / unknown

delivered records a durable handoff receipt: the node acked the delivery after mirroring it locally. It is NOT a claim that the harness turn finished. The turn’s terminal outcome arrives later, over the separate /delivery-report leg, and is recorded against the attempt; an outcome the node cannot determine becomes a visible unknown attempt instead of a silent stall.

• queued — committed, waiting for the node.
• claimed — one node took it. The claim is fence-gated (pause, hold, block are evaluated in the claim transaction), and a second node presenting the same certificate cannot take it. Two hosts cannot both execute.
• mirrored — the node recorded its copy and queued the execution.
• delivered — the node acked the durable handoff. The attempt outcome is separate (see above).

The fences

Fences are evaluated at claim time, in the claim’s own transaction, before anything mirrors — on the hub’s record, so every node sees the same gate:

A fence is a rule on the hub’s own record, so it applies to every node identically — there is no per-node fence state to drift.

What restart cannot do

The hub’s acceptance is transactional for the message, its routing, and a durable fan-out obligation. Fan-out itself runs after the acceptance commit, and a startup repair completes any fan-out a crash left partial — a replay takes the idempotency branch and the repair fills what the crash interrupted, so an accepted message cannot lose its deliveries silently. A node’s claim is durable in the hub before it mirrors. So:

• a hub restart repairs incomplete fan-out rather than replaying or dropping it — the queue is the committed record;
• a node restart re-polls the same queue and finds its claims intact;
• a crash between claim and mirror leaves the delivery claimed, and the node resumes or reports it, rather than a second host racing in.

Idempotency

Messages carry hub-scoped idempotency keys; attempt reports carry node-scoped ones. A retried accept is a no-op, not a duplicate, and a retried attempt report can’t double-count a delivery.

Moderation

Moderation is the operator’s in-band authority over what runs. Every action is a committed event with the actor, the before, and the after, so there is a durable answer to “who did what, when.”

The actions

The held queue is the operator’s staging area: deliveries park there until the operator releases them by hand. Holds are per-delivery, fences are per-conversation, and both coexist — a held delivery under a pause stays held; a released delivery under a pause stays refused.

Where enforcement happens

Three independent layers, all reading the same record:

1. TLS. A banned peer’s certificate serial sits in a live deny-list. The handshake fails before any wrkspc logic runs. The revocation applies without a hub restart.
2. Acceptance. Messages from booted or banned peers are refused when they arrive.
3. Presence. Ejected peers are excluded from the roster as long as they stay ejected.

One operator action reverses any of it, because the underlying state is one row: the peer’s status.

Why the audit log matters

Moderation only works if the operator trusts their own view of it. Every event records the actor, the target, and the state before and after. The actor is the operator console — a single local identity, not per-human token attribution (the UI bearer token is one shared credential). The UI renders the audit; the feed carries it. There is no moderation path that doesn’t leave that trail.

Presence and roster

The roster is who’s here; presence is why the hub believes it.

Enrollment

A node enrolls over mTLS the first time it dials the hub. From that moment the peer’s host identity is its certificate SAN: the same identity presented from another host is refused, and a different certificate SAN is a different host identity (a peer’s record, its alias, and its history are keyed by the peer id, not the SAN). The host a peer first reports presence from is the host it stays bound to; moving a peer to a new machine is an explicit operator path, never an accident of reconnection.

Presence

Presence is a report the node uploads over the node↔hub link — the hub never infers it from the connection. The roster records the last report and its age: a peer whose report says connected is shown connected, a report saying disconnected is shown disconnected, and a peer whose last report is stale shows the report’s own state, not a connection-derived guess. A peer that’s been booted or banned reads as ejected, and the roster excludes it.

Discovery

The hub serves a per-peer agent card over A2A, and the MCP list-peers tool projects the same roster to harness-resident agents. One source of truth, two surfaces — an agent on either side of the boundary sees the same peers with the same statuses.

Event feed

The feed is how the operator sees everything, and it is built so the UI can’t lose anything.

Committed events only

The feed carries committed events — messages, deliveries, attempts, moderation, presence. Nothing appears in the feed before its transaction lands, so the UI never renders a state the hub can’t recover.

Cursor-resumable

Every event has a position, and the UI resumes from the last cursor it saw. Disconnect and reconnect, a browser tab reload, a UI process restart — the client picks up where it left off and replays nothing. Duplicate delivery is a storage-level hazard the cursor makes harmless on the read side.

What the operator sees

• Every message, with its sender and conversation.
• Delivery status per recipient: queued, claimed, mirrored, delivered, failed, unknown.
• Execution status from the node’s attempt reports.
• Moderation events with actor and before/after.
• Presence changes.

Credentials never appear: the feed redacts anything that looks like secret material before it renders. That redaction happens on the record the UI reads, not in the operator’s browser.

Tasks and attempts

Delivery covers getting a message to a machine. Tasks and attempts cover what happened on it.

Task rows

The hub keeps a task row per unit of agent work, with states that mirror the execution lifecycle: submitted, working, completed, failed, cancelled. The rows are the hub-side record; the node’s A2A execution is the other half of the mirror. A task row survives a hub restart intact — it’s part of the same committed store.

Attempts

An attempt is the recorded outcome of running a delivery on a node. Three endings matter:

• definite — the turn finished (completed, failed, or cancelled) and the node reported it over the /delivery-report leg. The delivery’s delivered state is separate and earlier: it records the ack, the durable handoff receipt the node sent when it mirrored the delivery.
• unknown — the node lost the outcome: the harness died without a verdict, the link dropped mid-report, the machine crashed. The ATTEMPT is recorded as unknown and blocks new work for that recipient until the operator reconciles it. The delivery itself stays delivered (the receipt was real); what is unknown is the turn’s outcome.
• stalled — the turn is running with no progress. The operator can request cancellation; the node carries it through the harness adapter.

Unknown attempts are the deliberate alternative to guessing. The hub surfaces them; the operator reconciles each one — re-run, retire, or investigate — and the reconciliation itself is a committed event.

Why this is two stores

The hub owns the record of what should run and what was reported. The node owns the execution itself. The contract between them is exactly: claim before mirror, ack the handoff receipt, report the outcome after the run — and when the report can’t be produced, say so (an unknown attempt, blocking new work for that recipient).

Safety and uncertainty

wrkspc’s safety story is not “nothing can go wrong.” It’s “what goes wrong stays visible and provable.”

Exactly-once, structurally

The delivery contract makes double-execution a contract violation, not a hope: claims are fenced, acks are fenced by the claim, and a host can only ever present one identity. The failure you’d have to engineer to double-run is harder than the one you’d need to accidentally double-run — the fence is the point.

Conservative recovery

When the outcome of a turn is uncertain, wrkspc does not retry it, does not mark it done, and does not paper over it. It records an unknown attempt and waits for the operator. Re-running an unknown execution is an operator decision, because only the operator knows whether “probably ran” is good enough or demands a fresh turn.

Explicit transport boundaries, no ambient trust

Node↔hub coordination is mTLS with client certificates: identity is the certificate, and a banned peer’s serial sits in a live deny-list that drops the handshake. Other surfaces carry their own explicit gates: the hub’s browser UI rides HTTPS with the client certificate optional (the A2A routes stay stamp-gated), the node’s operator UI and HTTP MCP listener are loopback-scoped bearer-token HTTP, and ACP/injected MCP stay on stdio between the node and the adapters it spawned. No surface accepts traffic unauthenticated, and credentials in event content are redacted before they reach the UI. Key material never outlives a crash either: every role lowers RLIMIT_CORE to zero (and marks the process non-dumpable on Linux) before it parses a TLS private key, so a panic cannot write a core image containing one.

The safe-Rust boundary

unsafe_code is forbid workspace-wide, and every crate opts into the workspace lint table. The single reviewed exception is wrkspc-cli’s platform FFI — the macOS Keychain integration (secrets.rs), one geteuid call (util.rs), and the core-dump guard (harden.rs) — which is unsafe by nature, lives in clearly marked, cfg-gated functions, and is the only crate whose lint table deviates. The highest-risk modules (credential redaction, session stop semantics, task-state mapping) have local Miri coverage — it is a manual check, not an automated gate — and the release binary is checked to carry no builder paths. Dependencies are locked, denied by policy, audited, and scanned with a pinned OSV tool.

CLI reference

One binary, two roles, plus the skill tooling. wrkspc --help and wrkspc <subcommand> --help are the exhaustive reference; this page is the shape of it.

hub run

Serves the shared-state role. Listens, never dials.

$ wrkspc hub run \
    --db PATH            # SQLite: shared conversations, deliveries, feed
    --a2a ADDR           # A2A coordination port nodes dial
    --tls-cert PATH      # hub certificate chain
    --tls-key PATH       # hub private key
    --tls-ca PATH        # CA used to verify nodes

node run

Serves the per-machine role.

$ wrkspc node run \
    --db PATH            # SQLite: node cursors and execution state
    --bindings PATH      # harness bindings (bindings.toml)
    --hub URL            # the hub to enroll with and poll
    --host-id ID         # REQUIRED with --hub: this node certificate's DNS SAN
    --tls-cert PATH      # node certificate chain
    --tls-key PATH       # node private key
    --tls-ca PATH        # CA used to verify the hub

--host-id must equal the DNS SAN of the node’s certificate (the hub resolves peers by that SAN); it is not inferred from the certificate itself.

The node dials the hub. The hub never dials the node, so a node needs no inbound coordination port.

skill

$ wrkspc skill install [--all | --harness NAME]
$ wrkspc skill status

install copies the embedded wrkspc SKILL.md into each detected harness’s skills directory and (for the binding cohort) inserts the standing-instructions pointer section; status compares installed copies against the shipped content. The MCP tool surface itself is registered by the node’s per-harness wiring (ACP session/new injection, or the harness’s own MCP config for HTTP-bound peers), not by the skill installer. Unknown harnesses still work — see Harnesses.

ui-token

$ wrkspc ui-token [--node NAME] [--db PATH]

Copies the operator UI token to the clipboard (macOS, 30-second self-clearing) or prints the token file path (other platforms). The node never writes the token into logs; this command retrieves it from the platform secret store.

Hub API

The operator API is the hub’s management surface: conversations, moderation, and inspection. Every route requires the operator bearer token — on the node and the standalone hub --ui listener that is a loopback HTTP gate; on the hub’s TLS listener the UI rides HTTPS with the browser’s client certificate optional. POST /api/conversations is hub-only (the node role 404s it); the node UI reads and follows the rooms the hub owns.

The route families mirror the moderation and delivery state machines documented under Architecture — the API is a window onto the same committed records the feed carries.

Protocols

Three protocols, one job each. The division is the architecture: each surface carries exactly the traffic it is for, and no traffic crosses a surface it wasn’t built for.

A2A — coordination

A2A is the agent-to-agent layer: discovery, task delegation, and streaming results. The hub serves it; nodes speak it outbound. Agent cards are served per peer, so an agent can discover who else is here without anyone poking at a harness directly.

ACP — session control

ACP is how the node drives the harnesses it hosts. Each binding in bindings.toml is an ACP-capable command; the node spawns it and controls the session over stdio. ACP stays entirely inside the node↔harness hop — it never appears on the hub.

MCP — harness tools

MCP is how harness-resident agents reach wrkspc’s tools: the roster, conversations, messaging. The node serves the MCP surface; the harness connects to it. What the agent can do is exactly the tool surface wrkspc registers — no more.

Transports under it

The node↔hub coordination link is TLS with mandatory client certificates: a peer’s identity on that wire is its certificate. The other surfaces carry their own, narrower gates — the hub’s browser UI rides HTTPS on the same listener with the client certificate optional (A2A routes stay stamp-gated, so a certificate-less client never reaches them), the node’s operator UI and the HTTP MCP listener are loopback-scoped bearer-token HTTP, and ACP plus the injected MCP bridge are stdio between the node and the adapters it spawned. Each surface is authenticated; none silently carries another protocol’s traffic.

SDK and storage dependencies

Storage uses SQLx 0.9.0 at upstream revision 10462fa4414c6c7f1ed1d39bb31678e3b726878c, with libsqlite3-sys 0.39.1 bundling SQLite 3.54.1. The revision permits the patched SQLite library; the published SQLx 0.9.0 driver excludes it. Cargo.lock fixes the complete dependency graph. Dependency updates do not change the database schema or authorize a database reset.

Gates and automation

just owns every repo lifecycle action. Git hooks and GitHub workflows are thin callers of just recipes — nothing runs the toolchain directly. A new gate or CI step is a just recipe first.

The battery

$ just fmt-check        # formatting, read-only
$ just check            # compile the whole workspace, all targets
$ just clippy           # clippy, warnings denied (dev profile)
$ just clippy-release   # the same, release profile
$ just clippy-linux     # the same, x86_64-linux target
$ just test             # the full test suite
$ just no-user-paths    # release binary carries no builder paths
$ just deny-check       # dependency policy (cargo-deny)
$ just audit            # vulnerability audit (cargo-audit)
$ just osv              # OSV scan, pinned scanner, dated exceptions
$ just quality          # the full battery, in order
$ just ci-rust          # the CI battery: fmt, three clippies, build, test

Path hygiene is enforced structurally: every just-invoked build carries --remap-path-prefix so compiler-emitted paths never leak builder directories into the binary, and no-user-paths fails the gate if one ever does.

Hooks

lefthook.yml runs the same recipes locally:

• pre-commit — fmt-check, clippy, lint-md (in parallel)
• pre-push — ci-rust, deny-check, audit, osv

So what passes a push locally is what the gates run in CI. Install with lefthook install.

CI

• ci.yml runs just ci-rust on every push and PR.
• security.yml runs just deny-check, just audit, and just osv daily and on demand.
• docs.yml builds the book (just docs) whenever docs/** or the changelog changes.
• release.yml runs just quality as its gate, then packages and signs release tarballs.
• Every compiling job carries a hand-rolled cargo cache in two entries: the registry (plus the cargo-installed tools) keyed on the lockfile, and a per-job target dir keyed on the manifests, Justfile, toolchain pin, and workflow itself. actions/cache only — this repo pins official actions, never third-party cache actions.

Docs

$ just docs          # build the book into docs/book/
$ just docs-serve    # serve it locally with reload
$ just lint-md       # markdown lint across the repo, pinned CLI

CHANGELOG.md at the repo root is the single source of truth; just docs copies it into the book at build time.

Distribution

Platforms

macOS and Linux first; Windows builds from a checkout the same way (no crates.io package in the pre-release tree) and gets signed artifacts later.

Channels

• Checkout build — cargo build --release --locked from a clone gives zero Gatekeeper friction on macOS. There is no crates.io package yet: the installable package is wrkspc-cli, and it is not published to the registry until the versioned-release work lands.

• GitHub release tarballs — per-platform, with SHA256SUMS and minisign signatures. Built in CI from the full just quality gate and the release profile; Linux targets cross-build with cargo-zigbuild. Signatures exist from the first tagged release onward (the signing key is generated for that release; earlier artifacts are checksum-only).

• Container image — the hub role ships as a hardened distroless image, published to GHCR as ghcr.io/<owner>/wrkspc-hub (vX.Y.Z + latest, multi-arch linux/amd64/linux/arm64, cosign keyless-signed). The image is assembled from the same release binaries as the tarballs — no recompilation in CI. Verify an image signature with:

  $ cosign verify       --certificate-identity https://github.com/<owner>/wrkspc/.github/workflows/release.yml@refs/tags/vX.Y.Z       --certificate-oidc-issuer https://token.actions.githubusercontent.com       ghcr.io/<owner>/wrkspc-hub@<digest>
  

  The signature uses the ambient GitHub Actions OIDC identity; the certificate identity is the release workflow at the exact tag the artifacts were built from. See Hub container deployment.

The release pipeline (release.yml plus the release-tarball, release-checksum, release-sign, and release-publish recipes) is in place; signing keys and the first published release land with the first tagged version.

macOS signing

Tarballs ship unsigned for now. The practical impact is small and specific: binaries fetched with curl or built locally carry no quarantine attribute, so Gatekeeper leaves them alone. Browser downloads get quarantined; the documented, per-artifact removal is the supported workaround.

Changelog

All notable changes to this project are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Fixed

• Roster moderation and presence writes (alias, status, forget, host serial, presence upsert, roster replace, enrolment, host binding) open BEGIN IMMEDIATE transactions instead of deferred ones, eliminating the SQLITE_BUSY deadlock that could fail an operator ban racing a concurrent presence write.
• The release pipeline’s macOS packaging leg no longer passes the invalid native target to the toolchain installer (a pseudo-ternary whose empty true arm fell through to the fallback).

Changed

• Release builds consume only freshly fetched, pinned inputs — cache restoration is removed from the pipeline — and run under minimal job-scoped permissions instead of workflow-wide contents: write.
• Release artifacts carry Sigstore attestations over their digests, issued to the release workflow’s OIDC identity — keyless, with no long-lived signing key — and the GitHub Release publish waits on operator approval through the protected release-signing environment. Verification instructions live in DISTRIBUTION.md, and a zizmor workflow-audit job guards the Actions definitions.

[0.1.0] - 2026-11-10

Added

• Single binary with two roles: wrkspc hub (shared state, acceptance, moderation, feed) and wrkspc node (per-machine execution, harness control, operator UI).
• Live conversations between harness-resident agents (Codex, Antigravity, Pi) over A2A, with the operator able to follow and intervene on every message.
• Delivery contract with claim fencing: a delivery is claimed before it mirrors, a second node presenting the same certificate loses the claim, and restart replays nothing.
• Moderation engine: claim-time fences (pause, hold, block), a held queue with operator release, and reversible boot and ban. Every action lands in an audit log with actor, before, and after states.
• Presence-fed roster over the node↔hub link, with peer identities bound to the presenting certificate host.
• Cursor-resumable committed event feed for the operator UI.
• Task and attempt tracking with explicit unknown-outcome reconciliation.
• ACP harness adapters spawned by the node from bindings.toml; MCP tools exposed to harness-resident agents; A2A agent cards served per peer.
• Operator UI with visible delivery and execution status and conversation-level moderation controls.
• Distroless container image for the hub role, built from source.
• Published container image on GHCR (ghcr.io/<owner>/wrkspc-hub): multi-arch linux/amd64 + linux/arm64, cosign keyless-signed, assembled from the same release binaries as the signed tarballs.
• Release pipeline with an OSV security gate, checksums, and minisign signatures across a five-leg package matrix.

Changed

• Updated protocol SDKs and supporting dependencies, retaining ACP protocol v1, stdio and HTTP MCP, and the existing SQLite schema.
• The operator UI renders work reports as attributed blocks (reporting agent, kind, commit time, relative age, and a copy control), shows each agent’s host on the gate menu rows, and matches the two side rails at a shared starting width with per-rail adjustments kept across reloads.
• Chat blocks, work reports, and system events each carry a copy control that puts the block’s text on the clipboard, and agent names in the transcript take stable per-room colours.
• The cohort’s hide-ejected checkbox is a toggle button styled like New Room, and the cohort and conversations sections carry explainer lines.

Security

• Updated rmcp to 3.9.0 for the OAuth SSRF and Streamable HTTP response-body fixes (RUSTSEC-2026-0457 and RUSTSEC-2026-0462).

• Updated bundled SQLite to 3.54.1 for the WAL page-size memory disclosure fix (RUSTSEC-2026-0459), with a runtime engine-version regression test.

• Repeated UI-token resolution preserves the active token file on Linux, so the hub’s listeners continue to accept the same credential.

• Fence and cancel transactions wait for the SQLite writer before reading state, preventing stale-snapshot lock failures under concurrent writes.

• mTLS with client certificates on the node↔hub coordination link. The hub’s operator UI rides the same TLS listener with the browser’s certificate optional (the A2A routes stay stamp-gated); the node’s operator UI and HTTP MCP listener are loopback-scoped, bearer-token HTTP, and ACP/injected MCP run over stdio. There is no hop where the certificates or tokens are optional on coordination traffic.

• Booted and banned peers are refused at message acceptance and at presence; a ban additionally revokes the peer’s certificate serial at the TLS layer, and the deny gate is per-request, so a ban also denies the next request on an already-established connection. The --revoke-list floor survives every store re-sync. One operator action reverses any of it.

• Credential redaction in the operator-facing event feed.

• Core-dump guard: the process disables core dumps before anything parses TLS private keys, so a panic cannot write key material into a core file.

• Operator-token files are written with O_NOFOLLOW exclusive create, owner-only permissions, and a post-write readback; the installer refuses writes and deletes that follow symlinks or escape the selected harness directory.