Quickstart

Get a workspace running and ssh into it in a few minutes. This walks through a local Docker setup; for a real server see Deploy a server.

Prerequisites

• Docker running locally (the default compute provider).
• The hopboxd (control plane) and hopbox (CLI) binaries — build from source with make build, or grab them from Releases.

1. Start the control plane

hopboxd

hopboxd listens on localhost:7700 (API) and :7777 (agent dial-in), uses the Docker compute provider and a local home directory for storage, and creates an SSH user CA at ./hopbox-ssh-ca on first run. Leave it running.

2. Create a workspace

In another terminal:

hopbox create demo --image ubuntu:24.04
hopbox ls

The reconciler pulls the image, starts a container, and side-loads the agent, which dials back to hopboxd. Within a few seconds the workspace reaches Running.

3. Get a shell — the quick way

hopbox shell demo

This is an interactive PTY over the control plane (think docker exec), handy for a quick look. For real SSH tooling, set up certificates next.

4. SSH in (and VS Code, scp, rsync)

hopbox login            # mints a short-lived SSH certificate from the CA
hopbox ssh-config demo  # writes an ~/.ssh entry for `demo`
ssh demo

Now ssh demo, VS Code → Connect to Host → demo, scp, and rsync all work — no public port, no manual key wrangling. See SSH & VS Code for how it works and how to wire VS Code.

5. Expose a web app

hopbox create web --image ubuntu:24.04 --expose app:3000
hopbox get web        # shows the resolved https:// endpoint

Run something on port 3000 inside the workspace and it's reachable at a host-routed HTTPS URL.

Clean up

hopbox rm demo

Next

• What is Hopbox — the architecture in five minutes.
• Auth & multi-user — give each user their own boxes and keys.
• Deploy a server — run it for real with TLS.