hopbox

# hopbox **A compute-box substrate.** One daemon (`hopboxd`) turns a single host into a fleet of **isolated boxes you reach over plain SSH** — for humans *and* for AIs. ```sh ssh box@box.hopbox.dev ``` That one command spawns a Firecracker microVM and drops you into a root shell. **No signup, no client to install, no pre-created box** — your **SSH key is your identity** and the **username is the box spec**. It's live at **[box.hopbox.dev](https://box.hopbox.dev)** — try it. > Docs: **[hopbox.dev](https://hopbox.dev)** --- ## Ways in, one engine The same box fleet, through several front doors: | Front door | What it is | | --- | --- | | `ssh <name>@host` | Spawn/attach a box, get a shell. `scp`/`sftp`/`rsync`, `ssh <name>@host "cmd"`, and `ssh -L` port forwarding all work. | | `ssh cli@host` | A zero-install **management CLI over SSH** — `ls` / `up` / `rm` / `suspend` / `resume` / `rename` / `ready` / `snapshot` / `acc`, key-authed. | | browser terminal | Open a page, get a live shell over a WebSocket. Nothing to install at all. | | MCP plane | An **AI-control plane**: an AI watches the live fleet, delegates work to boxes, and renders interactive UIs a human drives. | The username is a small grammar: `name~backend:image:flavor+duration` — e.g. `ssh proj:python:big@host` is a 4-vCPU Python box named `proj`. ## What you get - **Real isolation** — Firecracker **microVMs** (hardware-isolated, per-box network fence) or **Docker** containers (zero-setup). Pick per daemon with `--compute`. - **Auto-suspend lifecycle** — an idle box is snapshotted to disk (compute freed) and **resumes on reconnect**, kernel/processes/TCP intact. Nothing is lost on disconnect. - **Accounts & sybil resistance** — `ssh cli@host acc register` verifies you via **GitHub device flow**; verified accounts get the **durable tier** (boxes never idle-reaped). **Per-key quotas** are the floor, so ten throwaway keys can't hoard compute. - **Persistent storage** — a per-box **home** that survives rebuilds, and a shared **`/wrk` workspace** (JuiceFS over S3) mountable from every one of your boxes. - **Snapshots & flavors** — `snapshot` / `fork` / `restore` a box's disk; size boxes with named flavors (`tiny`…`huge`). - **Detached jobs** — `box-guest run <cmd>` keeps a box alive until a long task finishes. - **AI-native** — the MCP control plane is built into the daemon, not bolted on. - **Measured, reproducible** — [`bench/bench.sh`](bench/) times cold spawn, resume, exec and transfers against any host through the front door. ## How it works ``` human (ssh) · AI (MCP) │ ┌──────┴───────┐ reverse dial ┌──────────────┐ │ hopboxd │ ◀─────────────────── │ box │ │ the daemon │ │ + agent │ └──────────────┘ └──────────────┘ ``` - **Boxes dial out.** The in-box agent opens a connection *to* `hopboxd` and keeps it; the control plane never routes *into* a box. Boxes work behind NAT, and your SSH session is proxied over that one reverse connection into the box's own SSH server. - **Declarative core.** A reconciler drives each box from its observed state toward its desired spec — the Kubernetes controller *pattern*, no Kubernetes dependency. ## Self-host ```sh # quick, docker-backed curl -fsSL https://raw.githubusercontent.com/hopboxdev/hopbox/main/deploy/install-hopbox.sh | sudo sh # full microVM host (Firecracker kernel + rootfs, systemd unit, front door) curl -fsSL https://raw.githubusercontent.com/hopboxdev/hopbox/main/deploy/provision.sh | sudo bash ``` Everything is configured from one YAML file — `hopboxd --config /etc/hopbox/hopboxd.yaml` (see [`deploy/hopboxd.example.yaml`](deploy/hopboxd.example.yaml)). ## Build from source ```sh go build -tags "docker firecracker" ./cmd/hopboxd # the daemon go build ./cmd/box-guest # in-box client go build ./cmd/hopbox-agent # in-box init/agent go test ./... ``` Layout: `cmd/` (binaries), `internal/core` (box engine, reconciler, accounts, metadata API), `providers/compute` (microvm, docker), `internal/verify` (GitHub/accounts), `docs/` (the VitePress site), `deploy/` (provisioner + example config). See [`ARCHITECTURE.md`](ARCHITECTURE.md). ## Status The box model, SSH access, and the accounts/verification layer are live on box.hopbox.dev. The AI-control plane (MCP + canvas loop) is newer and evolving.