Guide
Run your own wisp Grid
wisp Grid is what runs wisp Cloud, and it’s in the wisp repo (MIT). Put it on one small Linux server and everyone you let in gets their own wisp at name.wisp.example.com: signed in with GitHub, Google or your company’s OpenID Connect, sandboxed from each other, asleep when idle. grid.trywisp.dev runs on a Hetzner CAX21 (4 Arm vCPUs, 8 GB) for about €12 a month, which is enough for 4 people with agents running at once.
Free and open source · Claude Code, Codex, Cursor CLI, opencode, Antigravity CLI, Grok Build · macOS, Linux, Windows (beta) · Node 20+
Try it on your computer first
npx wisp-agents grid dev --fake-agentsOpen http://wisp.localhost:8080 and sign in with any email (dev sign-in). --fake-agents runs tasks with wisp’s test agents, so nothing needs an account.
1. Install it on a server
Debian 13 or Ubuntu 24.04, with ports 80 and 443 open. Copy the wisp repo there and run, as root:
DOMAIN=wisp.example.com ./grid/deploy/install.shIt installs Node.js 22, Docker with gVisor, Caddy and some swap, builds the image each person’s wisp runs in (git, gh, Claude Code, Codex, opencode), and sets up the firewall and the service. Then:
sudo -u wisp node bin/wisp.js grid init --domain wisp.example.com --data /var/lib/wisp-grid2. Point DNS at it
Two A records to the server’s address: wisp and *.wisp (for wisp.example.com). Caddy gets a certificate for each name the first time it’s asked for, after checking with the grid that the name belongs to someone.
3. Set up sign-in
- GitHub: github.com → Settings → Developer settings → OAuth Apps → New. Callback URL:
https://wisp.example.com/auth/github/callback. - Google: Google Cloud → APIs & Services → Credentials → OAuth client ID (Web). Redirect URI:
https://wisp.example.com/auth/google/callback. - Put each client id in
/var/lib/wisp-grid/grid.jsonand each secret in its own file undersecrets/(chmod 600). - Decide who gets in:
"allow": { "accounts": ["github:you"], "domains": ["example.com"], "githubOrgs": ["your-org"] }. - Turn on the sandbox:
"hostd": { "driver": "container" }.
sudo -u wisp node bin/wisp.js grid doctor --data /var/lib/wisp-grid
sudo systemctl enable --now wisp-gridHow people are kept apart
- Each person’s wisp runs in its own Docker container with gVisor, a user-space kernel between the agents and the host’s, with no capabilities and limits on memory, CPU and processes.
- Only its own home folder persists. The firewall blocks traffic between containers, to the host, to the cloud metadata service and to mail servers.
- Sign-in uses PKCE, state and checked ID tokens; each person’s cookie only works on their own address; devices sign in with a code and can be removed from the account page.
- Secrets the grid keeps are encrypted per person under a master key you can rotate (
wisp grid rotate-key). Agents’ logins never leave the person’s own folder.
Questions
- How big a server do I need?
- About 2 GB of memory per person with an agent running. A 4-core, 8 GB machine with swap handles 4 people at once.
- Does it need KVM or bare metal?
- No. gVisor runs on ordinary cloud VMs, Arm or x86.
- Can people use the desktop and phone apps with my grid?
- Yes. In Settings → Cloud, or on the phone app’s first screen, they type your grid’s address instead of grid.trywisp.dev.
- Where is the full reference?
- grid/README.md in the wisp repo: commands, configuration, secrets and isolation.
Related guides
- Use wisp CloudYour own wisp on a server: sign in with GitHub, close the laptop, read the report on your phone.
- Run coding agents on multiple machinesYour desktop, a dev box, a cloud VM: one prompt, several machines, one queue.
- Connect your machines with TailscaleLaptop, desktop, server and phone on one private network: SSH in from anywhere, with no open ports.