Collaboration

Workbench can share a workspace with other Workbench users so that multiple people participate in the same agent session in real time. Participants see messages as they arrive, can send their own prompts, and vote on plan approvals. Connections default to Tailscale networking for zero-config authentication and encryption, but can be relaxed for LAN-only use. Collaboration is always available — no experimental toggle required.

Quickstart: pair with a teammate

This walkthrough gets two people into a shared session in about five minutes. One person hosts, the other joins. Both need Workbench installed and Tailscale running.

Before you start (both people)

1. Install Tailscale if you haven’t already. Sign in so both machines appear on the same tailnet.
2. Confirm Tailscale is connected — the Tailscale menu bar icon should show “Connected” and both machines should be visible in your Tailscale admin console.
3. Open Workbench. The Share button is in the sidebar toolbar. You can optionally set a display name in Settings > Collaboration — it shows up in the participant roster so the other person knows who you are.

Host: create the share

1. Open the workspace you want to collaborate on. If you want to share multiple workspaces (say, the frontend and the API), you’ll select them all in the next step.
2. Click the Share button in the workspace header (or sidebar).
3. Click New share.
4. Check the workspaces you want to include. Your teammate will only see these — nothing else on your machine.
5. Turn on Collaborative — this lets the other person send prompts, not just watch. Leave it off if you only want them to observe.
6. Optionally turn on Require unanimous plan approval. When on, a plan won’t execute until every participant votes to approve it. Good for pairing on consequential changes; skip it for exploratory work.
7. Give the share a name (e.g. “Design review with Sarah”) or leave it blank.
8. Click Mint share.
9. Copy the connection string and send it to your teammate through Slack, iMessage, email — whatever you trust. The string contains the address, port, and a one-time token.

Tip

The connection string is a secret. Anyone who has it can join your session until you revoke the share. Don’t post it in a public channel.

Guest: join the share

1. Click + Add remote in the sidebar footer.
2. Paste the connection string you received.
3. Workbench connects over Tailscale. The shared workspace appears in your sidebar alongside your local workspaces.

That’s it. You’ll see the agent’s messages, tool calls, and diffs in real time. If collaborative mode is on, type a prompt and it goes straight into the shared session.

During the session

• One person at a time can have an active agent turn. If the agent is running on your prompt, the other person’s input area shows that a turn is in progress. Once it finishes, either person can send the next prompt.
• Plan consensus (if enabled): when the agent enters plan mode and wants to execute, every participant gets a vote. The plan runs only after unanimous approval. If anyone denies, the agent sees the denial reason and can adjust.
• Participant roster: both of you see who’s connected in the sidebar — each shared workspace shows a collapsible collab(N) subtree listing all participants with their role (host, turn holder, muted). The host can right-click a participant for moderation actions. Display names come from Settings > Collaboration > Display name (falls back to the OS hostname if blank).

When you’re done

The host can revoke the share at any time:

1. Click Share in the workspace header.
2. Find the active share in the list.
3. Click Stop. This immediately disconnects all participants who joined through that share and invalidates the connection string.

The guest can also disconnect by right-clicking the remote workspace in the sidebar and choosing Disconnect.

If you’re on the same LAN without Tailscale

Both machines must still have Workbench, but you can skip Tailscale:

1. On the host, go to Settings > Collaboration and turn off Require Tailscale network.
2. Create the share as normal. The connection string will use the host’s LAN IP instead of a Tailscale address.
3. The guest pastes the connection string and connects over the local network.

The TLS encryption and share-token authentication still protect the connection. You lose the Tailscale identity guarantee — anyone on the same network with the connection string can join.

---

Reference

Collaboration settings

Collaboration is always available. Configure display name, default consensus, and Tailscale networking in Settings > Collaboration. The Share button in the sidebar toolbar opens the share dialog.

Sharing a workspace

1. Open the workspace you want to share.
2. Click the Share button in the workspace header.
3. Click New Share.
4. Select one or more workspaces to include in the share.
5. Toggle Collaborative mode to allow participants to send messages (not just observe).
6. Toggle Require unanimous plan approval if you want every participant to approve before a plan executes.
7. Click Mint Share to generate the share.
8. Copy the connection string and send it to your collaborators through a trusted channel.

The connection string contains the host address, port, and a single-use share token. Anyone who has the string can join until you revoke the share.

Joining a shared workspace

1. Click + Add remote in the sidebar footer.
2. Paste the connection string you received.
3. Workbench connects and the shared workspace appears in your sidebar alongside your local workspaces.

You will see live messages, agent output, and tool calls as they happen. If collaborative mode is enabled, you can send your own prompts into the session.

Tailscale networking

By default, Workbench only accepts collaboration connections from Tailscale IP addresses (the 100.x.y.z range). This means both the host and the joining user must be on the same Tailscale network. Tailscale handles encryption, identity, and NAT traversal, so collaboration works across networks without port forwarding or VPN tunnels.

If you do not use Tailscale and both machines are on the same local network, disable the Tailscale requirement in Settings > Collaboration > Require Tailscale network. When disabled, connections are accepted from any IP address on your network. The TLS + share-token layers still protect the connection, but you lose the Tailscale identity guarantee.

Dynamic pairing challenges

First-time connections use a dynamic pairing challenge instead of pre-shared session codes. When a new client connects to a share:

1. The host generates a fresh 6-character alphanumeric code.
2. The host sees a pending challenge notification with a live countdown (5-minute TTL).
3. The client enters the code in a pairing input field.
4. After verification, the client is admitted. Codes expire after 5 minutes or 3 failed attempts.

Native notifications alert the host when a new challenge arrives.

File tab sync

File tabs opened by the host sync to connected clients in real time. Open, close, and switch events are pushed via room broadcast. File content (up to 100 KB per file, with a 300 ms debounce) is included so clients see the same editor state. On reconnect, clients receive the current tab state via join-session snapshot hydration. Remote tabs appear as read-only mirrors on the client.

Browser tab sync

When a localhost HTTP/S link is clicked in chat, it opens as an in-app webview tab. During collaboration, these webview tabs sync to clients via a localhost proxy so both host and client see the same browser tab content.

Shared terminal tabs

Terminal tabs are shared between host and client during collaboration sessions. Terminal output streams to connected participants alongside chat and file content.

Sidebar member tree

Connected collaborators now appear under all shared workspaces in the sidebar, not just workspaces the client has actively opened. Each shared workspace shows a collapsible participant subtree with roles and moderation controls.

Join grace period

After a client verifies their challenge code, the host-side join notification is suppressed for 5 minutes for that participant. This lets short disconnects and reconnects complete silently without alerting the host each time. An explicit host disconnect revokes the grace immediately.

Features

• Workspace-scoped shares — each share grants access to specific workspaces, not the entire machine.
• Participant roster — each shared workspace shows a collapsible subtree in the sidebar listing connected participants, their roles, and moderation controls for the host.
• Turn lock — only one participant can have an active agent turn at a time, preventing conflicting edits.
• Plan consensus — optionally require all participants to approve a plan before it executes.
• Share revocation — revoke a share at any time to disconnect all participants who joined through it.
• Join notifications — when a remote user connects, the host sees a modal dialog naming the user and listing which workspaces they joined. The modal plays a notification sound (configurable per-event via notification_sound_user_joined) and fires a native OS notification banner when the app is in the background. Multiple joins queue and display one at a time.
• Real-time delivery — sequence-based gap detection with automatic delta recovery and live attachment events.
• Data hydration recovery — if initial data hydration fails after pairing, the client retries with bounded backoff (1s/3s/5s) and shows loading/failure/retry UI instead of silently showing “No repositories”.

Security

Collaboration connections are protected by three layers:

1. TLS / TOFU — all traffic is encrypted with TLS. The joining client pins the host’s certificate fingerprint on first connection (trust-on-first-use), the same model used by Remote Workspaces.
2. Share token authentication — the connection string contains a cryptographic token. Only users who possess the token can join. Revoking the share invalidates the token.
3. Tailscale IP enforcement (default) — connections are rejected unless they originate from a Tailscale IP address (100.x.y.z). This binds access to your Tailscale network’s identity layer. Can be disabled for LAN-only use.

Troubleshooting

Problem	Fix
”Collaborative” checkbox is greyed out in the Share dialog	Tailscale isn’t connected or isn’t installed. Check the status hint below the checkbox — it tells you what’s missing.
Guest gets “connection refused”	Make sure both machines are on the same Tailscale tailnet (or same LAN if Tailscale requirement is off). Check that the host’s firewall allows the server port (default 7683).
Guest connects but can’t send prompts	The share was created without Collaborative mode. The host needs to stop the share and mint a new one with collaborative mode enabled.
Plan consensus vote never resolves	All participants must vote. If someone is idle or disconnected, their vote is missing. The host can revoke and re-share without consensus if needed.
Client shows “No repositories” after connecting	Initial data hydration may have failed. The client should see a retry button; click it to re-request data from the host. If the issue persists, disconnect and reconnect.
Share dialog shows “Another application is using the Tailscale serve port”	A different service has claimed the Tailscale serve mapping on port 443. Run tailscale serve status to see what’s there, remove the conflicting mapping, then retry.

See also

• Settings — collaboration settings reference
• Remote Workspaces — single-user remote access (non-collaborative)