Documentation
Everything Pupitre does on your server, written down.
From an empty Ubuntu machine to a project running behind a URL. Every page says what Pupitre does, what it asks of you, and what it leaves behind.
Get started
From an empty VPS to a project served behind a URL.
- Install the app and link it to your account Downloading the app for macOS, Windows or Linux, what each system shows the first time, and linking the app to your Pupitre account.
- Choose a VPS What Pupitre needs from the machine you rent, and what to look at before you pay for one.
- Your key The SSH keys Pupitre generates, where the private halves live on your computer, what reaches the server, and how to reuse them elsewhere.
- Connect the app Adding a server, what the first connection does, and what the inspection reports back.
- The onboarding, step by step Every step the app walks a server through, from the address to a machine ready to work, with what changes on the machine at each one.
Services
What every module of the catalogue installs, and what it asks you for.
Base
- System Base packages, sized swap, memory guard, a dev user with sudo, zsh, tmux, git identity, the dev command.
- Hardening ufw on SSH only, fail2ban, root closed and passwords off once a key opens dev.
- Backups Configuration, secrets, databases and projects, encrypted on the server and sent to your own S3 bucket on the interval you set.
Runtimes
- Node.js Node, Bun, pnpm and Yarn through mise, at the versions you choose, in every shell.
- Java Temurin through mise, Gradle daemon sized for the RAM.
- Python uv and the Python version you choose, through mise.
- Go Go at the version you choose, through mise, with GOPATH and go install binaries on the path.
- PHP PHP at the version you choose, built by mise, Composer optional, memory limit yours.
- Ruby Ruby at the version you choose, built by mise, Bundler optional.
- Docker Docker Engine and Compose, dev in the group so no command needs sudo, images where you want them.
- Rust Rust at the chosen version through mise and rustup; cargo, rustc and what cargo install builds on every shell’s path.
Databases
- MySQL or MariaDB Bound to 127.0.0.1 on the port you pick, app and remote accounts you name, dumps in ~/dumps imported for you.
- PostgreSQL The major version you choose, local only, app and remote roles you name, common extensions, dump import.
- MongoDB The major version you choose, local only, the app user you name, mongodump import.
- Redis Local only, a password it refuses to work without, persistence and a memory ceiling you set.
- Mailpit A local SMTP server that catches everything your projects send, and the interface that shows it, both on the loopback.
AI agents
- Claude Code The native binary, checksum verified, with the machine context, the Pupitre skills and your own subscription.
- Codex Installed through mise, same machine context and same skills, on your own subscription.
- Cursor CLI Cursor’s own package under its version, the agent and cursor-agent commands, the Pupitre skills, on your Cursor subscription.
- Gemini CLI Google’s open-source agent through mise, same machine context and same skills, on your Google account — the free tier is enough — or an API key.
- GitHub Copilot CLI Copilot’s terminal agent through mise, same machine context and same skills, on your Copilot subscription.
- OpenCode The open-source agent, its binary checked against the digest GitHub publishes, tied to no provider: a Claude, ChatGPT or Copilot subscription, or any key.
- Hermes Agent Nous Research’s agent through Python, the model providers you configure, a systemd service if always on.
- OpenClaw The personal assistant reached from Telegram, Discord or WhatsApp, its gateway as a systemd service, the model providers you configure.
- Headless browser Headless Chrome and the libraries it needs, which the screenshot tool of Pupitre’s MCP server uses to show a page to the AI agent.
Remote editors
- JetBrains Remote Dev Remote backend preinstalled for IntelliJ IDEA, WebStorm, PyCharm, PhpStorm or GoLand, JVM sized, your licence.
- VS Code Remote SSH code CLI and remote server preinstalled so the first connection is immediate; same for Cursor and Windsurf.
- Zed Remote Server Remote server preinstalled for your version, opened through zed://ssh.
Exposure
- Cloudflare Tunnel One tunnel on your own Cloudflare account, one route per project, DNS and certificate managed.
- Caddy Reverse proxy with automatic Let’s Encrypt certificates, one route per project, for a domain outside Cloudflare.
- Tailscale The machine on your tailnet through an auth key: SSH and preview URLs from your phone or another computer, nothing exposed publicly. Lives beside Caddy or the tunnel.
Tools
- GitHub gh, HTTPS clone without a key, the server’s key registered on your account.
- 1Password CLI and service account token, checked at install time, so a project builds its env file from your vault.
- Neon The Neon CLI and your API key in the dev shell; your projects and branches stay yours to create.
- Wrangler Cloudflare’s CLI and your API token in the dev shell; Workers, D1 and Pages deploy from the server.
- Vercel The Vercel CLI and your token in the dev shell; deploy, env and logs answer from the server.
- Supabase The Supabase CLI, its release binary checksum verified, and your access token in the dev shell; migrations, types and functions push from the server.
- Stripe The Stripe CLI, its release binary checksum verified, and a restricted key in the dev shell; stripe listen forwards webhooks to a project on the machine.
Every day
Projects, terminals, agents and editors once the machine is up.
- Dashboard and activity What the app shows of a machine between two pieces of work, and what it lets you stop.
- Projects Adding a project, what the agent does with it, and how it reaches a URL.
- Terminals How the app opens shells on the server, what tmux gives you, and what happens when you close the window.
- Secrets The credentials a server keeps for its services, where they live, and how you change one.
- Your own client Connecting Claude Code, Codex, your terminal and your editor to a Pupitre server over SSH, with the private key the app generated.
- AI agents Claude Code, Codex, Cursor, Gemini, Copilot, OpenCode and Hermes on the server — how they are installed, what context they get, and where you sign in.
- MCP server The tools Claude Code and Codex get on the server to start projects, read logs and look at a page, and what they cannot do with them.
- Remote editors JetBrains Gateway, VS Code Remote SSH and Zed against a Pupitre server.
- Services and updates Adding, configuring, updating and removing a module after the first install.
- Backups What a backup holds, setting up your own S3 bucket, the passphrase, and restoring a server.
- Access to addresses Who can open a published project, access keys, and how a browser, an app or a script presents them.
Account
Teams, the licence, security, the questions that come back, troubleshooting and uninstalling.
- Signing in How you open the console and the app, passkeys, the second factor, and what to do when a device is lost.
- Teams Organisations, members, roles, assigning a server to a person, and revoking access.
- Licence The free servers, the licence beyond them, what counts as a server, and what happens when the right to use Pupitre stops.
- Security What Pupitre can and cannot do on your server, and how to check each claim.
- Questions The questions that come back, answered without hedging.
- Troubleshooting A server that asks for a licence, restricted mode, fail2ban banning your own address, the sudo password of dev, an install step that failed, and where the app writes its errors.
- Uninstall Removing a server from the console, the agent from the server, the app's line from ~/.ssh/config, and the app with its data folder.