runed

What it is

In plain terms, runed is the thing that runs the agent. When a turn needs to happen, runed starts one fresh Docker container, lets the agent work inside it, then throws the container away.

runed is the execution plane: a pure container-spawner. It serves the work queue, starts one Docker container per spawn, enforces the run timeout, and brokers a downscoped capability token for that single spawn. It is the only daemon wired to the Docker socket. It never appends a message (routd is the sole appender) and never signs a token (authd is the sole signer).

runed owns runed.db and migrates it itself — the runtime tables (spawns, session_log, spawn_logs, mcp_tokens) that have no home in routd.

Why it exists

A turn is one ephemeral container run. (See the Turn primitive.) Something has to own the Docker socket, and only one thing should: the socket is the keys to the host, so concentrating it in one small daemon keeps the blast radius small. runed is that daemon.

Spawning a container is more than docker run. runed has to apply the egress allowlist so the agent can only reach approved hosts, enforce RUNED_RUN_TIMEOUT so a runaway turn can’t burn forever, steer a live run with SIGUSR1, and tear the container down cleanly (stop, then kill, then rm -f). It also brokers a per-spawn token from authd that is downscoped to exactly that turn’s folder — so a container that escapes still can’t act outside its grant.

Without runed, routd would have to hold the Docker socket itself, mixing the routing plane with host-level container control. Keeping them apart means the daemon that talks to the network (routd) is not the daemon that can start processes on the host (runed).

How it fits

routd
        |  POST /v1/runs   (scope runs:run)
        v
      runed   broker downscoped per-spawn token  <-- authd
        |     docker run --rm  (egress allowlist, ipc dir mounted)
        v
      arizuko-ant container   runs one turn, then exits
        |     agent tools  -->  routd /v1/turns/{turn_id}/*
        |                       (MCP socket hosted in routd, not runed)
        +-- timeout / SIGUSR1 steer / stop->kill->rm -f --> runed

Inputs: POST /v1/runs from routd (the routd↔runed contract); a service:runed token from authd it uses as the parent when brokering each spawn token. Outputs: a running container; status and kill over /v1/runs/{run_id}; spawn and session rows in runed.db.

Hard deps: the Docker socket on the host; authd as the token broker and JWKS source; routd, which hosts the per-turn MCP socket and receives the agent’s tool calls. The agent runs inside crackbox — the containment boundary whose egress allowlist runed enforces.

Timeouts and shutdown

RUNED_RUN_TIMEOUT (default 20m) is the run ceiling, and it bounds two things at once: the container hard-kill, and the in-container agent query timeout (ARIZUKO_QUERY_TIMEOUT_MS = RUNED_RUN_TIMEOUT − 30s). The 30-second gap lets the agent abort and deliver a graceful summary before runed kills the container under it. On graceful shutdown runed detaches in-flight runs, so containers outlive the daemon and a restart doesn’t murder a turn mid-sentence.

Standalone usage

runed runs as a daemon, but it cannot do its job without a Docker socket to spawn into and an authd to broker tokens from. It also expects routd to host the MCP socket the container talks to. Run it only alongside those.

cd /srv/data/myinstance
export DATA_DIR=/srv/data/myinstance
export LISTEN_ADDR=:8080
export AUTHD_URL=http://authd:8080
export AUTHD_SERVICE_KEY=$(grep ^AUTHD_SERVICE_KEY .env | cut -d= -f2)
export RUNED_RUN_TIMEOUT=20m
export CONTAINER_IMAGE=arizuko-ant:latest
# the host docker socket must be reachable
./runed

With AUTHD_URL unset the verifier runs open and the broker hands out a static token — local-dev only. GET /health returns 200 once the process is up; the red flag is spawns stuck in state=queued, which means the broker or Docker is unavailable.

What runed does not do

runed does not route messages, does not append to the message log, and does not sign tokens. It takes a run request, produces a container, enforces its limits, and reports the result — the execution plane, nothing else.

Go deeper

concepts/primitives — the Turn primitive: one ephemeral container run per event.
components/crackbox — the box the agent runs in, whose egress allowlist runed enforces.
reference/env — split daemons — the wiring vars; container spawn vars under container.
components/routd — sends the run, hosts the MCP socket the container calls back on.
runed/README.md — the run contract, timeout math, file map.
specs/5/P — the execution plane split.