Installation

Podspawn is a single binary that works as both server and client. Same install, different commands. Install it once and it handles both roles.

Requirements

Server:

• Linux (any distro -- Ubuntu, Debian, RHEL, Alpine all tested)
• Docker installed and running
• OpenSSH 7.4+ (for the restrict keyword)
• Root access

Client:

• Any SSH client on any OS works without podspawn
• Install the podspawn binary for .pod namespace routing (optional but recommended)

Interactive setup (recommended)

One command installs the binary, configures sshd, registers your SSH keys, and runs diagnostics:

curl -sSf https://podspawn.dev/up | bash

The script auto-detects whether you're on a server (sshd + Docker present) or a client machine and walks you through setup interactively.

On a server, it will:

1. Download and install the podspawn binary
2. Run podspawn server-setup to configure sshd
3. Ask how you want to register SSH keys (GitHub, existing key, generate new, or paste)
4. Run podspawn doctor to verify everything works
5. Enable the cleanup timer if systemd is available

On a client, it will:

1. Download and install the podspawn binary
2. Add the .pod namespace block to ~/.ssh/config
3. Ask for your default server hostname

Manual server setup

If you prefer step-by-step control:

Step 1: Install the binary

curl -sSf https://podspawn.dev/install.sh | sh

Or from source:

go install github.com/podspawn/podspawn@latest

Or via package manager:

# Homebrew (macOS/Linux)
brew install podspawn/tap/podspawn

# Debian/Ubuntu (.deb)
# Download from GitHub releases:
# https://github.com/podspawn/podspawn/releases
sudo dpkg -i podspawn_*.deb

# RHEL/Fedora (.rpm)
sudo rpm -i podspawn_*.rpm

Step 2: Configure sshd

sudo podspawn server-setup

This appends AuthorizedKeysCommand to /etc/ssh/sshd_config, creates directories, and reloads sshd. It's idempotent -- safe to run multiple times.

Step 3: Register a user

Import keys from GitHub:

sudo podspawn add-user alice --github alice

Or use a local key file:

sudo podspawn add-user alice --key-file ~/.ssh/id_ed25519.pub

Or paste a key directly:

sudo podspawn add-user alice --key "ssh-ed25519 AAAA... alice@laptop"

Step 4: Verify

sudo podspawn doctor

This checks Docker, sshd, permissions, disk space, and image cache. Fix any failures before proceeding.

Step 5: Test

ssh alice@localhost

You should land in a container. Type exit to leave.

Client setup

The client binary is optional. Without it, you SSH directly to the server hostname. With it, you get the .pod namespace:

ssh alice@backend.pod    # requires client binary
ssh alice@yourserver.com  # works with any SSH client

macOS / Linux

curl -sSf https://podspawn.dev/up | bash

Or install manually:

# Install binary
curl -sSf https://podspawn.dev/install.sh | sh

# Configure SSH client
podspawn setup

Windows

No installer needed. Add this to ~/.ssh/config (or C:\Users\you\.ssh\config):

Host *.pod
    ProxyCommand podspawn connect %r %h %p
    UserKnownHostsFile /dev/null
    StrictHostKeyChecking no

Download the binary from GitHub releases and place it in your PATH.

Configure server routing

Create ~/.podspawn/config.yaml:

servers:
  default: devbox.company.com
  mappings:
    gpu.pod: gpu-server.company.com
    personal.pod: homelab.ddns.net

Now ssh alice@backend.pod routes to devbox.company.com, and ssh alice@gpu.pod routes to gpu-server.company.com.

localhost.pod always resolves to 127.0.0.1 without any config.

Updating

podspawn update

This checks GitHub for the latest release, downloads it, and replaces the binary. Existing SSH sessions are not affected.

Check for updates without installing:

podspawn update --check

What gets installed

Next steps