Workbench Server

Workbench Server (workbench-server) is a headless backend for running Claude Code agents on a machine without a desktop environment — a Linux VM, a Mac mini, or any always-on box. Desktop and mobile clients connect to it over an encrypted WebSocket to browse repos, drive chat sessions, and use terminals as if they were local. It’s the same server the desktop app embeds when you click Share this machine; the standalone binary just lets you run it without a GUI attached. See Remote Workspaces for the full connection and collaboration model this page assumes.

Package overview

Workbench ships as three independent packages — install what you need:

Package	What it provides	When to use
workbench-cli	workbench command-line client	You want CLI access to a running Workbench instance
workbench-server	workbench-server headless backend	You want to run agents on a headless machine
workbench-desktop (Homebrew cask: workbench)	Workbench GUI application	You want the full desktop experience

workbench-server depends on workbench-cli — your package manager installs it automatically as a matching-version dependency.

Installation

APT (Debian / Ubuntu)

# Add the r26d signing key and repository (if not already configured)
curl -fsSL https://updates.r26d.dev/apt/r26d-archive-keyring.gpg | sudo tee /usr/share/keyrings/r26d-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/r26d-archive-keyring.gpg] https://updates.r26d.dev/apt stable main" | sudo tee /etc/apt/sources.list.d/r26d.list

sudo apt update
sudo apt install workbench-server

This automatically installs workbench-cli as a dependency.

Homebrew (macOS)

brew install r26d/tap/workbench-server

The formula depends on r26d/tap/workbench-cli, which Homebrew installs alongside it.

Direct download

Download the latest workbench-server-<version>-<os>-<arch>.tar.gz tarball from the downloads page. Extract it and install the binary:

sudo install bin/workbench-server /usr/local/bin/

Tarballs have no package manager to pull in a dependency, so install the CLI client separately — workbench-server doesn’t strictly require workbench on PATH to run, but the owner/share workflow below assumes the desktop or mobile app is driving it from another machine, and any local scripting needs the CLI too.

Upgrading from apt install workbench

If you previously installed Workbench via sudo apt install workbench, that package now installs as a transitional metapackage — it pulls in both workbench-desktop and workbench-cli automatically, and apt upgrade continues to work. It doesn’t install workbench-server; add that separately if you want a headless backend.

Starting the server

workbench-server

On first run this generates a self-signed TLS certificate (cert.pem / key.pem, via rcgen/rustls) in the server’s config directory and starts listening. By default it binds 0.0.0.0 on port 7683 and advertises itself via mDNS on the local network:

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

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

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

The console output never prints pairing tokens — only share list and owner mint, run explicitly from a local terminal, do that.

CLI options

Flag	Default	Description
--port <port>	7683	WebSocket port to listen on
--bind <address>	0.0.0.0	Bind address
--name <name>	hostname	Display name shown to connecting clients
--no-mdns	off	Disable mDNS advertisement
--config <path>	<config dir>/workbench-server/server.toml	Config file path (~/.config/workbench-server/server.toml on Linux, ~/Library/Application Support/workbench-server/server.toml on macOS; override the parent directory with $WORKBENCH_SERVER_CONFIG_DIR)

Subcommands

workbench-server share list                    # Print connection strings for active shares
workbench-server owner mint --label <name>      # Mint a full-machine owner credential
workbench-server owner revoke <id>              # Revoke one owner credential by id
workbench-server owner revoke --all             # Revoke every owner credential

share list and both owner commands read and write the same config file the desktop app uses, so a share created from the GUI’s Share this machine modal shows up here too — the headless binary doesn’t need to be the thing that created it.

Owner connection security

An owner credential grants the paired client full access to this machine’s Workbench — every repository and workspace, workspace lifecycle, and repo terminals. It’s the model you want when the remote machine is your own (a workstation you drive from a laptop), as opposed to workspace-scoped collaboration shares, which stay GUI-only. See Remote Workspaces → Owner mode for the full feature walkthrough; this section covers the security properties.

• Local-only minting. workbench-server owner mint --label <name> is the only way to create or escalate to owner scope, and it only runs as a local terminal command on the server machine (SSH is fine — there’s no network RPC that can do this). It creates the config file and TLS certificate if they don’t exist yet, then prints one workbench:// connection string containing the host, port, pairing token, and the server’s certificate fingerprint (#fp=…).
• Fingerprint pinning, not trust-on-first-use. Because the owner connection string embeds the certificate fingerprint, the client verifies it’s talking to that exact server before sending anything on the first connection — unlike scoped shares, which use trust-on-first-use the way SSH’s known_hosts does.
• Challenge-response pairing. Authentication is an HMAC challenge-response exchange — the raw pairing token never crosses the wire, and there’s no approval-code prompt (a headless server has nowhere to show one; the pinned certificate plus proof of token possession are the credential).
• No tokens in logs. The server’s console output and startup banner never print tokens — share list and owner mint are the only commands that do, and they’re deliberate, interactive, operator-invoked actions.
• Revocation kills sessions immediately. workbench-server owner revoke <id> (see the id in share list) or owner revoke --all removes the credential from the config; every session it issued dies on its next request and the client shows Re-pair required. If the server process is currently running, restart it — it holds the config in memory and would otherwise overwrite the change on its next save.
• Owner ≠ host. An owner session can change this machine’s app settings (see Settings target) and its agent-backend configuration and secrets, but it still cannot manage shares, mint or revoke owner credentials, or stop the server without its local control token — and it can’t be minted or escalated remotely; only that local command can create one.

Best practices

• Mint credentials only from a local terminal session on the server machine (a systemd/SSH session on the box is fine).
• Use --label to name credentials so you can tell devices apart in share list.
• Revoke a credential as soon as a device is lost or no longer trusted.
• Keep the server behind a firewall and expose only the configured port; all traffic is TLS-encrypted, but pointing it directly at the open internet is still more exposure than most setups need.

Connecting from desktop or mobile

1. On the server: workbench-server owner mint --label "my laptop"
2. Copy the printed workbench:// connection string.
3. On the client: open Workbench, then + Add remote in the sidebar footer (desktop) or the Advanced entry (mobile).
4. Paste the connection string. Pairing completes without an approval-code prompt.
5. The server appears in the sidebar as a connection group, with repos and workspaces alongside your local ones.

For LAN setups the server also shows up automatically under Nearby via mDNS (unless started with --no-mdns); for machines reached over Tailscale or a VPN, the manual connection string above is the way in. See Remote Workspaces for reconnection behavior, running the server under systemd, and the full owner-mode feature set.