Self-hosted runners

A runner is a machine you own that runs the fountain runner daemon. It can be a Mac mini under the desk, a home server or a GPU box.

It is the fourth sandbox provider, and the one whose control plane sits on your side of the network. The daemon dials out to Fountain, holds one connection, and serves sandboxes for an agent whose sandbox_provider is runner. There is no inbound port, it works behind NAT, and nothing bills you by the minute.

A backend decides the substance of a sandbox. The default backend makes it a directory, and the agent's processes belong to the machine. On Linux with KVM, --backend firecracker makes it a microVM instead. Read a microVM for each sandbox for that one.

Three reasons to want one.

• Hardware Fountain cannot rent. A Mac, for Xcode, a macOS-only toolchain or a local model on Apple silicon. A GPU. A machine on your LAN that holds something the agent needs.
• State that stays. The sandbox is the agent's memory. A machine that never shuts down has nothing to park and nothing to pay for.
• A setup you own outright. A self-hosted Fountain and your own machines need no vendor account at all.

ADR 0022 holds the design.

Summary

Read this first: trusted mode

This section is about the default backend, which is --backend process.

A runner sandbox is a directory on the machine. The agent's processes run as you, with your network, your PATH and your tools. There is no VM, no container, no sandbox-exec, and no egress policy between the agent and the machine.

Fountain points HOME at the sandbox directory. Dotfiles, skills and .env land there and stay with that one conversation. That is the whole of the isolation.

Run it on a machine where you would hand a capable colleague a shell. If that is more trust than you want to give, put the sandboxes in microVMs instead.

Start one

fountain auth login                       # once; a full-scope API key
fountain runner                           # name = this machine's hostname
fountain runner --name mini --root ~/work/fountain-sandboxes

The daemon logs runner: connected, then stays in the foreground. Run it under launchd, systemd, tmux, or whatever keeps a process up on that machine. Ctrl-C stops it, and stops its sessions, because a runner's processes belong to the daemon. It reconnects with backoff on any drop. It gives up only when Fountain refuses the key, rejects the name, or has runners switched off.

Then pin an agent to it. Use Agents, then edit, then Sandbox provider, then runner, or send sandbox_provider: "runner" to POST /api/agents.

Fountain places a new conversation for that agent on your most recently connected online runner. Start one while no runner is online and it fails plainly, with no_runner_online and HTTP 409. It does not queue.

Account, then Runners, or GET /api/runners, lists each machine that has connected, with live online status. DELETE /api/runners/:id forgets one. A daemon that you left up reconnects and registers itself again.

What the machine needs

It needs what the Sprites base image has, on the PATH of whoever starts the daemon. That is bash, git, node, npm, npx, and bun for opencode.

Fountain installs the agent CLIs at provision, the way it does everywhere else, with npm install -g. They go into the sandbox's own npm prefix, <sandbox>/.npm-global, so Fountain writes nothing to your global node install. The npm cache is your real ~/.npm.

Fountain adds /opt/homebrew/bin, /usr/local/bin, ~/.local/bin and ~/.bun/bin to PATH when they exist. So a daemon that launchd starts with a minimal environment still finds Homebrew.

Two things translate, and two do not.

/tmp is the machine's /tmp. The gemini and opencode workspaces live there, and each sandbox sees the same ones, as it does inside one Linux sandbox.

A microVM for each sandbox

--backend firecracker replaces the directory with a Firecracker microVM. The sandbox gets a kernel, an init and a root filesystem of its own. Its processes cannot reach the host.

This is the VM mode that ADR 0022 named and did not build. ADR 0036 holds the design.

fountain runner --backend firecracker \
  --bridge fcbr0 --subnet 10.61.0.0/24 \
  --fc-kernel /var/lib/fountain/vmlinux \
  --fc-rootfs /var/lib/fountain/rootfs.ext4

What the host needs

Four things.

• Linux with KVM. The daemon reads /dev/kvm at startup and refuses to start without it.
• The firecracker executable, on the PATH or at --fc-bin.
• CAP_NET_ADMIN, because the daemon makes a tap device for each microVM.
• A bridge, which you make. Give it the first host address of --subnet, which is 10.61.0.1 for the default.

The daemon writes no firewall rule and no NAT rule. Your network is yours, and a daemon that changed it would go past its invitation. Attach the bridge to whatever the sandboxes must reach, and put the rules you want in front of it.

The base image

--fc-rootfs is an ext4 image. Each sandbox starts as a private copy of it. That copy is the agent's memory between turns, and the daemon never replaces it. cp --reflink=auto makes the copy. On XFS or Btrfs it costs almost nothing. Elsewhere it costs a full copy.

The image must hold three things.

• The packages a sandbox needs, which are bash, git, node, npm, npx and bun for opencode.
• The fountain binary, built for the guest architecture.
• An init that starts fountain runner-guest at boot.

A systemd unit is enough.

[Unit]
Description=Fountain runner guest agent
After=network.target

[Service]
ExecStart=/usr/local/bin/fountain runner-guest
Restart=always

[Install]
WantedBy=multi-user.target

fountain runner-guest serves one sandbox, /home/sprite, over vsock. It serves it with the same backend that a trusted-mode runner uses. A command in a microVM therefore behaves as a command on the machine does. The isolation is the boundary around the guest, and not a second way to run a command.

The daemon refuses a microVM that boots but never answers, and says which part is absent. A sandbox that accepted a create and then hung on every turn would be worse.

How a request reaches the guest

Firecracker publishes a guest's vsock ports on the host as a unix socket. The daemon opens it, asks for port 1024, and gets a stream to the agent. Over that stream runs the same protocol that Fountain speaks to the daemon.

Two things the daemon must get right, and both are about order.

• A spawn's replay must not pass the spawn's own reply. The daemon holds the guest's frames until the reply is on the wire to Fountain.
• A microVM that dies in the middle of a turn must not read as success. Fountain reads a stream that stops with no exit frame as exit 0, so a dropped link ends each live session with exit 137.

What is different

The contract table below describes the process backend. Four rows change.

A wake is automatic. The daemon boots a microVM that is down, and resumes a paused one, before it forwards a request. A sandbox that Fountain never resumed still answers, as a Sprites sandbox does on its next exec.

Limits

• Egress policy is still not advertised. A microVM makes one possible, because each sandbox has a tap device of its own. The capability is a property of the adapter and not of one runner, so a Fountain change must come first. Nobody built it.
• A brokered tenant cannot use a runner. With credential brokerage on for an account, Fountain refuses a conversation on any provider that does not advertise an egress policy. Every runner is such a provider, microVM or not. The launch fails with backend_lacks_network_policy before a sandbox exists. BROKER_ALLOW_UNENFORCED=true lifts the refusal on a development instance, and the real fix is the row above.
• A park keeps the RAM. See the suspend row above.
• The base image is yours to build. Fountain ships no image.
• One host. The daemon puts each microVM on the machine it runs on.

How the contract maps

On the team page and the API

An accepted ACP turn keeps its place during a transient runner socket drop. Fountain holds the turn busy for up to two minutes while the runner reconnects, including when the server boots before the runner returns. It attaches to the same process and prompt instead of submitting the prompt again. A reconnect does not extend a pending permission's original timeout.

The runner switches both replay and live output to the new connection. Fountain skips earlier turns in that process journal before restoring the active turn, so an old permission request cannot replace the one currently waiting. If the runner does not return within the recovery window, the turn fails and becomes available for a new prompt. Interrupting the turn cancels recovery. Stopping the runner daemon still terminates its processes.

A teammate whose sandbox lives on a runner shows where it runs. The roster entry's sandbox, and that of each conversation object, carries provider, one of sprites|e2b|daytona|runner. For a runner it also carries runner: {id, name, hostname, online, path}. That names the machine and the sandbox directory on it, so a client can say "on mac-mini · ~/…" and parse no sandbox name.

Presence tells "asleep" apart from "the machine is off". While the runner is not connected, the teammate is machine_offline, which reads as "machine offline · wakes when the runner reconnects", and not asleep or away. A message cannot wake it.

POST /api/team/:agent_id/messages and POST /api/conversations/:id/prompts answer 503 runner_offline with Retry-After until the daemon returns. That is the shape provisioning uses.

A scheduled run on such a teammate waits the way a busy one waits.

A runner that connects or drops sends a team event on /api/team/stream. A roster then notices that the machine came back, and polls for nothing.

Configuration

The daemon reads the usual CLI settings, which are FOUNTAIN_API_KEY, FOUNTAIN_BASE_URL and --profile. It needs a full-scope key. A sandbox's own per-conversation token cannot attach a machine that would then run the account's agents.

The wire protocol

One WebSocket, with JSON text frames, at GET /api/runners/ws?name=… with the bearer key. Fountain sends the requests. The daemon replies by id, and streams frames for the sessions that somebody asked about.

→ {"id":7,"op":"spawn","name":"runner-…","cmd":"claude-agent-acp","args":[],"env":[["K","v"]],"dir":"/home/sprite","stdin":true,"detachable":true}
← {"id":7,"ok":true,"result":{"session_id":"s-…"}}
← {"stream":"stdout","session_id":"s-…","data":"<base64>","replay_for":7}   replay, to the requester only
← {"stream":"stdout","session_id":"s-…","data":"<base64>"}                  live, to every subscriber
← {"stream":"exit","session_id":"s-…","code":0}
→ {"id":8,"op":"stdin","session_id":"s-…","data":"<base64>"}
← {"id":8,"ok":false,"error":"command_exited"}

The ops are create get destroy list suspend resume write_file exec spawn stdin stdin_close detach list_sessions attach. The errors are the contract's codes: not_found, command_exited, not_supported, invalid, unavailable and write_failed.

Managoat.Runner.Connection is the server end, and cli/internal/runner is the daemon. Managoat.Runner.FakeDaemon is a daemon inside the BEAM that the conformance suite runs against. It is the executable description that both ends must agree with.

Related

• About sandboxes, for why honest capabilities change the lifecycle.
• The sandbox contract.
• Change sandbox lifetimes. A provider without :suspend would destroy on idle, and a runner does advertise it.