Remote Workspaces

Workbench can connect to workspaces on another machine over an encrypted WebSocket connection. The local app discovers or connects to a remote server and displays remote repos, agents, and terminals alongside local ones.

Use with your own account only

Agents started on a remote Workbench server run under whatever Claude credentials are configured on the server machine. If you pair multiple devices to a server signed into your Claude Pro/Max account, all of those devices share that single subscription identity.

Anthropic’s Consumer Terms prohibit making your account “available to anyone else.” Pair only your own devices to a server tied to a Pro/Max subscription. If you need to share access with a teammate, use API-key authentication on the server and have your teammate sign in with their own credentials.

Sharing from the Desktop App

Click Share this machine in the sidebar. The server starts automatically as a subprocess — no separate installation required. The server is embedded in the Workbench binary (gated behind the default-enabled server feature).

The Share this machine modal shows the new share’s connection string directly (and as a QR code, so you can pair the Workbench mobile app by scanning with your phone). The server’s own console output never prints tokens — it’s just a startup banner and an active-share count:

workbench-server v0.8.0 listening on wss://0.0.0.0:7683
Name: Work Laptop

Certificate fingerprint: 3f:9a:...

Hostname: work-laptop — 1 active share(s). Run `workbench-server share list` to print connection strings.
Ready for connections.

Headless Server (Standalone)

For headless machines without a GUI, the standalone server binary is still available:

# Build and install the standalone server binary
cargo install --path src-server

# Start it (generates a TLS certificate on first run)
workbench-server

The standalone binary has no GUI of its own to create a share from, but it reads and writes the same server.toml config as the Workbench desktop app. So the usual flow is: start workbench-server on the machine, then open the Workbench GUI on that same machine and click Share this machine to mint a share (workspace scope, label, collaborative or not). Once the share exists, print its connection string from the headless side with:

workbench-server share list

This works even after you close the GUI — the share lives in the config file, not in the GUI process.

Connecting from the Local App

Automatic (LAN)

If both machines are on the same network, the server appears automatically in the sidebar under Nearby. Click Connect and enter the pairing token when prompted.

Manual

Click + Add remote in the sidebar footer and paste the full connection string. Workbench authenticates, stores a session token, and reconnects automatically on future launches.

Owner mode

Workspace-scoped shares are built for collaboration: you pick which workspaces a guest can see. When the remote machine is your own — a workstation you drive from a laptop while traveling — you want the opposite: everything, including things a share can’t grant. That’s an owner credential:

• Full access: every repository and workspace on the machine, creating and archiving workspaces, and repo terminals for trunk-workflow repositories. The terminal panel spawns shells on the server in the workspace’s worktree — the first tab auto-opens, + adds more, and shells survive workspace switches by re-attaching to the server-side PTY.
• Terminal-only minting: workbench-server owner mint --label laptop run locally on the server machine (over SSH is fine). It creates the config file and TLS certificate if needed and prints one connection string. There is deliberately no way to mint or escalate an owner credential over the network — the only writer is that local command.
• Hardened pairing: the printed string ends in #fp=<fingerprint> — the server certificate’s SHA-256 — so the client verifies it is talking to that exact server before sending anything (no trust-on-first-use window). Pairing itself is an HMAC challenge-response: the raw token never crosses the wire, and there is no approval-code prompt (a headless server has nowhere to show one; the pinned certificate plus proof of token possession are the credential).
• Remote focus mode: when the laptop connects with an owner credential, the window switches to showing only that server’s world, with a persistent accent-tinted badge naming the server. Back to local returns to your own repos; clicking the connection header re-enters. The badge is the standing reminder that files and terminals live on the remote machine.
• Owner ≠ host: owner sessions still cannot change the server’s app settings or manage its shares, and collaboration shares are completely unaffected — their pairing flow, approval codes, and workspace scoping are unchanged.

Revoke with workbench-server owner revoke <id> (or --all); every session the credential issued dies on its next request, and the laptop shows Re-pair required. share list (CLI) and the GUI’s share list both mark owner entries.

Server Management

# Print paste-able workbench:// connection strings for every active share
# (owner entries are marked; uses Tailscale-aware hostname when available)
workbench-server share list

# Mint / revoke an owner credential (local terminal only)
workbench-server owner mint --label laptop
workbench-server owner revoke <share-id>
workbench-server owner revoke --all

# Bind to a specific interface or port
workbench-server --bind 192.168.1.50 --port 9000

# Disable mDNS advertisement
workbench-server --no-mdns

To revoke a collaboration share, close it from the Workbench GUI (Share this machine > close the share). Owner credentials are revoked from the terminal as above (the GUI can also stop them from the share list).

Security

All traffic is encrypted with TLS. The local app pins the server’s certificate fingerprint on first connection (trust-on-first-use), similar to SSH’s known_hosts. This means:

• The first connection requires manual verification of the pairing token
• Subsequent connections are authenticated automatically via the pinned certificate
• If the server’s certificate changes, you’ll be prompted to re-verify

Owner connection strings go one step further: they embed the certificate fingerprint (#fp=…), so even the first connection verifies the server before any credential material is sent, and the owner pairing token itself never crosses the wire (HMAC challenge-response).

Roaming and reconnection

Workbench treats a remote connection as something that survives laptop lids and network changes:

• The client sends a WebSocket keepalive ping after ~25 seconds of idle. If the server doesn’t answer within 10 seconds, the connection is declared dead — so half-open connections after sleep or a network switch are detected without you running anything.
• Connections with auto-connect enabled reconnect automatically and indefinitely, backing off up to 30 seconds between attempts. Opening the laptop lid or joining a new network triggers an immediate retry.
• While offline, your last-known remote repositories and workspaces stay visible (dimmed) in the sidebar. A successful reconnect replaces them with a fresh snapshot from the server — unread and attention badges catch you up on what happened while you were away. Joined remote terminal sessions re-attach automatically after reconnect.
• Auth or certificate failures stop automatic retries and mark the connection Re-pair required; reconnecting silently is never attempted in that state. A TLS fingerprint change is never retried through the trust prompt. Error messages show only 8-character fingerprint prefixes so full fingerprints never reach logs or the console. Fix the cause (or re-pair) and click Connect.
• Manually disconnecting a connection sticks — window focus and network events will not silently reconnect it. The connection waits for you to click Connect again (or remove and re-add it).

Headless server over Tailscale

A common roaming setup: a headless server on an always-on machine, reached from a laptop over Tailscale from anywhere.

1. Mint the credential on the machine (SSH is fine — no GUI needed). For your own always-on box, use an owner credential:

   workbench-server owner mint --label laptop
   # → workbench://your-machine:7683/<token>#fp=<fingerprint>

   Then add the connection on the laptop with + Add remote, pasting the full string. Pairing completes without a code prompt. (For a machine you share with others, mint a workspace-scoped share from the GUI instead — see Sharing from the Desktop App.)

   mDNS discovery does not cross networks, so the Nearby list won’t show the server remotely — the manual connection string is the way in. TLS uses fingerprint pinning (embedded in the owner string), so the tailnet hostname works fine.

2. Keep the server alive across reboots with a systemd user unit at ~/.config/systemd/user/workbench-server.service:

   [Unit]
   Description=Workbench remote server
   After=network-online.target
   
   [Service]
   ExecStart=%h/.cargo/bin/workbench-server
   Restart=on-failure
   
   [Install]
   WantedBy=default.target

   systemctl --user enable --now workbench-server
   loginctl enable-linger "$USER"   # keep it running while logged out

   Session tokens and the TLS certificate persist across restarts, so a reboot at home never forces a re-pair from the road.

3. Back home, either keep using the headless server (connect the desktop GUI to localhost as a remote) or stop it and launch the GUI natively — both use the same database, so workspaces and history are already there.

---

Original source: utensils.io/claudette