Get a Docker host

A remote Docker engine that starts when you connect and stops when you leave.

A Docker host is a Linux machine running Docker, reached from your docker CLI over SSH. Builds, images, containers and volumes live there, so your laptop stays cool and its disk stays free. It starts when you run a command and stops when you've been away for 10 minutes.

You need Docker's CLI on your machine (Docker Desktop, OrbStack, or the plain docker client) and an SSH key.

  1. Have an SSH key

    The host lets in only the SSH keys registered for it.

    your terminal
    # skip if ~/.ssh/id_ed25519.pub already exists
    ssh-keygen -t ed25519
    cat ~/.ssh/id_ed25519.pub
  2. Create the host

    In the dashboard, open Docker hosts and fill in Create a Docker host: a name, a size, and the public key you just printed. The name becomes the user in its address, so my-laptop gives ssh://my-laptop@ssh.raftrun.com:2222.

  3. Connect

    your terminal
    # once: trust RaftRun's SSH host key
    ssh-keyscan -p 2222 ssh.raftrun.com >> ~/.ssh/known_hosts
    
    # point Docker at your host, in this terminal
    export DOCKER_HOST=ssh://my-laptop@ssh.raftrun.com:2222
    docker run --rm hello-world

    The first command waits about 15 to 30 seconds while the host starts. After that, commands answer at once.

  4. Reuse one connection

    Docker opens a new SSH connection for every command. Add this to ~/.ssh/config on macOS or Linux to keep one open, which makes each command several times faster.

    ~/.ssh/config
    Host ssh.raftrun.com
      ControlMaster auto
      ControlPath ~/.ssh/control-%C
      ControlPersist 10m

Keep it on every terminal

export DOCKER_HOST lasts for one terminal. A Docker context remembers the host for every terminal and every tool that follows Docker's current context.

your terminal
docker context create raftrun --docker "host=ssh://my-laptop@ssh.raftrun.com:2222"
docker context use raftrun

docker context use default goes back to your local Docker. Working on several projects? Give each folder its own host instead; see One host per project.

Things to know

  • Bind mounts point at the host's disk, not your laptop's. -v $(pwd):/app mounts an empty folder on the host. docker build sends your folder as usual, and to edit code in a running container, sync it in: see Use your local files.
  • Published ports are private. Open them on your machine through SSH; see Open a service.
  • It is x64 Linux. Images build for linux/amd64, also from an Apple silicon Mac.
  • It is yours. Each host belongs to the person who created it, and only their keys get in.

Permission denied (publickey)

Your machine offered SSH keys the host doesn't have. The host's row on the Docker hosts page shows the key it accepts and, after a refusal, the keys that were offered instead. Compare them with the keys on your machine:

your terminal
# the keys SSH offers, in order
ssh -v -p 2222 my-laptop@ssh.raftrun.com true 2>&1 | grep -E "Offering|denied"

# the fingerprint of each key you have
for f in ~/.ssh/*.pub; do ssh-keygen -lf "$f"; done

If one of your keys matches the host's but SSH doesn't offer it, it has a name SSH doesn't try by itself. Name it in ~/.ssh/config:

~/.ssh/config
Host ssh.raftrun.com
  IdentityFile ~/.ssh/my_raftrun_key
  IdentitiesOnly yes

If none match, the key was pasted from another machine. Use that machine, or create a host with this machine's key.

Next