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 executoris 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}/output | download the artifact (control plane re-verifies its hash) |
POST /v1/runs/{id}/cancel, DELETE /v1/runs/{id} | cancel / clean up |
GET /healthz | liveness |