Self-hosting Maven
Run the harness and desktop app on infrastructure you control.
Maven is local-first by default: the harness listens on loopback, agent CLIs run on your machine, and application state lives under ~/.maven.
Typical self-hosted setup
- Run Maven on your personal macOS, Windows, or Ubuntu computer.
- Install and authenticate the agent CLIs you want to use separately; the npm Maven package does not include them. Use the same operating-system account for setup and the running server.
- Add optional third-party keys only for the services you need.
- Keep the harness on loopback.
- Use it from other devices by pairing them.
maven serveprints one pairing link for the way in you choose; paste it into the desktop app under ＋ → Connect to a server, open it in a browser, or scan its QR with a phone.
| You have | Run |
|---|---|
| HTTPS in front already (cloudflared, Caddy, nginx) | npx maven serve --public-url https://maven.example.com |
| A domain name, ports 80 and 443 open | npx maven serve --domain maven.example.com |
| Tailscale | npx maven serve --tailscale |
| Only this network | npx maven serve --lan |
| Nothing at all | npx maven login, then npx maven serve --tunnel |
A code works once, for 10 minutes. npx maven pair makes another, and npx maven devices lists the paired devices. See Deploy on a VPS for a server from scratch, and Networking.
For a Linux service, the VPS guide covers account setup, browser installation, and unattended startup. Installing browser libraries as administrator still requires installing the browser in the service user's home. The service runs an installed, chosen release; upgrading it is an explicit step.
Stop the server before a filesystem backup. Application state under .maven is only part of a complete backup: preserve the service user's engine credentials, browser state, and external workspaces too. See Data and backups.
What is still third party
Self-hosting Maven does not self-host every optional provider:
- Agent providers authenticate and bill through their own CLI or API.
- Composio owns connected-app OAuth grants unless you replace that integration.
- Boat owns managed cloud computers.
- ElevenLabs or Fish Audio synthesizes speech when its hosted voice engine is enabled. On Windows and Linux, Fish Audio also turns what you say into text for Take turns calls and dictation.
These services are optional. Local chat through a locally installed agent CLI does not require them.
Run headless during development
pnpm install --frozen-lockfile
pnpm dev:serverThe main harness listens on 127.0.0.1:8799 by default. Keep it private; it owns agent processes, approvals, computers, and workspace configuration.