podspawnInstallation
Install podspawn for local development, team servers, or remote access
Podspawn is a single binary with two modes: local (solo, no SSH) and server (multi-user, via sshd). If you're connecting to someone else's server, see Client mode below.
| Install path | Who it's for | What you need |
|---|---|---|
| Local | Solo devs on macOS/Linux | Docker runtime (OrbStack, Docker Desktop, Colima) |
| Server | Teams sharing a Linux box | Linux + Docker + sshd + root |
| Client | Connecting to a remote server | The podspawn binary |
Local mode
The fastest path. No root, no SSH, no sshd configuration. Just Docker and the binary.
Interactive install
Run the install script
curl -sSfL https://podspawn.dev/up | bashChoose Local when prompted. The script installs the binary, verifies Docker is reachable, and runs an optional setup wizard.
Complete the setup wizard
The wizard is all menu-based (no typing required). It asks:
- Use case -- web dev, systems programming, data science, or general
- Shell -- bash, zsh, or fish
- Base image -- Ubuntu 24.04, Debian 12, or Alpine 3.20
- Database -- none, PostgreSQL, MySQL, or Redis only
- Cache -- Redis yes/no (if you picked a database)
Based on your choices, it generates two files:
~/.podspawn/config.yaml-- local defaults (image, shell, cpus, memory, lifecycle)~/.podspawn/podfile.yaml-- a default Podfile with packages and services matching your picks
Hit Enter at each prompt to accept the defaults (Ubuntu 24.04, bash, no database). You can skip the wizard entirely by answering "n" when asked "Set up now?".
Start using podspawn
podspawn create dev # create a persistent machine
podspawn shell dev # drop into a shell
podspawn run scratch # one-shot throwaway containerYou can edit the generated config files anytime. See the Podfile reference for all options.
Manual install
brew install podspawn/tap/podspawncurl -sSfL https://podspawn.dev/install.sh | shgo install github.com/podspawn/podspawn@latestRequirements
- Docker running locally (OrbStack, Docker Desktop, or Colima all work)
- No root access needed
- No SSH setup needed
Local mode talks to Docker directly. There's no sshd involved, no key management, no network configuration. If docker ps works, podspawn works.
Server mode
For teams. A shared Linux box where users SSH in and land in isolated containers.
Interactive install
curl -sSfL https://podspawn.dev/up | bashChoose Server when prompted. The script will:
- Install the podspawn binary
- Run
podspawn server-setupto configure sshd withAuthorizedKeysCommand - Register SSH keys (from GitHub, a file, or pasted directly)
- Run
podspawn doctorto verify everything works - Enable the cleanup timer if systemd is available
Manual install
Install the binary
curl -sSfL https://podspawn.dev/install.sh | sh# Download from GitHub releases:
# https://github.com/podspawn/podspawn/releases
sudo dpkg -i podspawn_*.debsudo rpm -i podspawn_*.rpmConfigure sshd
sudo podspawn server-setupThis appends AuthorizedKeysCommand to /etc/ssh/sshd_config, creates directories, and reloads sshd. Idempotent, safe to run multiple times.
Register a user
sudo podspawn add-user alice --github alicesudo podspawn add-user alice --key-file ~/.ssh/id_ed25519.pubsudo podspawn add-user alice --key "ssh-ed25519 AAAA... alice@laptop"Verify
sudo podspawn doctorSince server-setup has been run, doctor runs all 11 checks: Docker, sshd, keys, permissions, disk space, and image cache. Fix any failures before proceeding.
By default, containers are ephemeral (destroyed after a grace period). Set session.mode: persistent in the server config or per-user overrides for workspaces where files survive across sessions. See Session Lifecycle for details.
Requirements
- Linux (Ubuntu, Debian, RHEL, Alpine all tested)
- Docker installed and running
- OpenSSH 7.4+ (for the
restrictkeyword) - Root access
Client mode
Connect to a remote podspawn server. The binary is optional but gives you .pod namespace routing.
Install
curl -sSfL https://podspawn.dev/up | bashChoose Client when prompted. Or install manually:
# Homebrew (macOS/Linux)
brew install podspawn/tap/podspawn
# Or download the binary
curl -sSfL https://podspawn.dev/install.sh | shConfigure
# Set up SSH config for .pod namespace
podspawn setup
# Point to your team's server
podspawn config set servers.default devbox.company.comConnect
# With .pod namespace (requires podspawn binary)
ssh alice@backend.pod
# Without podspawn, plain SSH works too
ssh alice@devbox.company.comAdvanced routing
Create ~/.podspawn/config.yaml for multiple servers:
servers:
default: devbox.company.com
mappings:
gpu.pod: gpu-server.company.com
personal.pod: homelab.ddns.netlocalhost.pod always resolves to 127.0.0.1 without config.
Windows
No installer needed. Download the binary from GitHub releases, place it in your PATH, and add this to C:\Users\you\.ssh\config:
Host *.pod
ProxyCommand podspawn connect %r %h %p
UserKnownHostsFile /dev/null
StrictHostKeyChecking nomacOS Gatekeeper: If you install manually (not via Homebrew), macOS may block the binary. Allow it in System Settings > Privacy & Security, or remove the quarantine attribute:
xattr -dr com.apple.quarantine /usr/local/bin/podspawnUpdating
podspawn updateDownloads the latest release and replaces the binary. Existing sessions are not affected.
Check without installing:
podspawn update --checkWhat gets installed
Created by the setup wizard:
- config.yaml -- local defaults (image, shell, resources, lifecycle)
- podfile.yaml -- default Podfile (packages, services from wizard choices)
Created by server-setup:
Created by setup:
- ~/.ssh/config --
.podnamespace block (appended) - ~/.podspawn/config.yaml -- server routing configuration
Next steps
How is this guide?