Run

Architecture

            ┌──────────── control plane (exuvia serve) ────────────┐
 UI / API ──►  graph · freshness · scheduler · run history · agent │
            │  artifacts (.exuvia/)                                 │
            └───────────────┬──────────────────────────────────────┘
                            │ Executor interface
              ┌─────────────┴──────────────┐
     LocalExecutor (default)        RemoteExecutor ──HTTP──► exuvia executor
     warm subprocess pool                                   (stateless container)

The control plane is the only stateful part. Executors run one node at a time and return a content-addressed artifact; they hold no project state.

  • Local (default): a pool of pre-warmed, single-use subprocesses on the same machine.
  • Remote: exuvia executor is a plain HTTP service — the same image runs on Cloudflare Containers, Fly, Cloud Run, Kubernetes, or a box under a desk. Point a control plane at it with --executor URL / EXUVIA_EXECUTOR_URL. Every request flows control plane → executor (project zip, upstream artifacts in; logs and artifact out), so a laptop can drive a cloud executor without being reachable from it. Project bundles are hash-verified and cached on the executor, so unchanged code is not re-sent.

Executor protocol (bearer EXUVIA_EXECUTOR_TOKEN):

Route
HEAD/PUT /v1/bundles/{hash}is this project version cached / upload it (zip, verified against the hash)
PUT /v1/runs/{id}/inputs/{dep}upload an upstream artifact
POST /v1/runs/{id}run; NDJSON response: {"type":"log"} lines then one {"type":"result"}
GET /v1/runs/{id}/outputdownload the artifact (control plane re-verifies its hash)
POST /v1/runs/{id}/cancel, DELETE /v1/runs/{id}cancel / clean up
GET /healthzliveness