Mains Server runs the same backend and web interface without Electron. It supports macOS and Linux and requires Node.js 22.12 or newer.
Install and start
The default bind is 127.0.0.1:8787. Startup creates a persistent owner token in the data directory.
Authenticate providers on the server host. Claude and Copilot runtimes are bundled; Codex and Cursor need their CLIs installed there. A desktop login on another machine is not copied to Server.
Open in a browser
Create a one-use login link:
The code expires after five minutes. The browser exchanges it for origin-bound session cookies without storing the owner token in the URL.
If the browser reaches the server through another configured origin:
Reach the server from another device
For a trusted LAN:
For Tailscale HTTPS:
Or keep the default loopback bind and connect a desktop through SSH.
A public TLS proxy must support WebSocket upgrades. Advertise its address explicitly with --public-url so clients receive a usable endpoint.
Pair and revoke devices
The server can print a five-minute, single-use QR for a phone when a reachable endpoint is configured.
Each paired phone has its own revocable token. Re-pair a revoked device rather than giving it the owner token.
Run as a service
This installs a macOS LaunchAgent or Linux systemd user service. Use --lan instead when you want trusted LAN access.
Uninstalling the service retains data, tokens, and logs. The service runs as your user; keep that host and account available.
Data and credentials
On macOS, Server opens the Desktop data directory by default:
On Linux, the default is $XDG_CONFIG_HOME/mains, falling back to ~/.config/mains.
Desktop and Server cannot own the same data directory at the same time. Quit Desktop before starting Server, and stop Server before reopening Desktop. The ownership lock rejects concurrent access.
--data-dir for an isolated backend:
Server cannot decrypt Desktop’s macOS Keychain-backed integration tokens. Reauthorize each integration on Server; its separate credential preserves the Desktop entry.
Browser capabilities
The web interface supports runs, files, document previews, Git controls, and Code terminal streaming on the backend.
Desktop-only features include the embedded browser, Lens, native MCP app extensions, Dock/menu bar integration, and desktop auto-update. Server runs agent work without those native surfaces.
Use mains --help for CLI options and mains --version for the installed version. 