Build against the
control plane.

Get a governed run — one that actually pauses for your approval — in about five minutes.

The object model, in the order you meet it. Each of these is a real API object; none of them is decorative. If you only read one page before integrating, read this one — the most common mistakes are all vocabulary mistakes.

An agent is a stable name with an append-only history. Every property that shapes behavior lives on a revision; a run always uses the latest revision at creation and freezes it into the RunSpec. Nothing here is ever edited in place — that is what keeps last month's audit trail meaningful.

A run is one governed execution of an agent: an immutable specification, a fresh sandbox, a live event timeline, and a terminal record with a diff and a cost report. The API calls runs sessions; the two words mean the same object.

"Borrow the agent, on demand": any external circumstance — an API call, a cron tick, a webhook — can start a run of a registered agent and get the outcome delivered back, signed. Every entry point converges on the same governed run path (frozen RunSpec, policy gate, budgets); a trigger never widens what an agent may do.

There is exactly one place in fluidbox where "can this happen?" is answered. Every tool call — from the model's own Bash to a brokered MCP call reaching a customer's Jira — passes through it, and the order of its stages is the security model.

A policy is evaluated on every tool call an agent makes. The verdict is one of allow, deny, or approve (pause for a human). Policies live in the control plane as append-only versions: the Governance page is the authoring surface, every publish is an immutable version with an author and a summary, and every run freezes a snapshot of its policy's latest version into the RunSpec — editing a policy only affects future runs, never in-flight ones.

The pause in the middle of a run. When the permission gate resolves a tool call to approve, the run enters awaiting_approval, an approval.requested event appears on the timeline, and the tool call blocks until a human decides — or the approval expires.

There are exactly two tool classes, and the split is the security model:

Two Docker paths: the eval stack (published images, one command, nothing built locally) and the from-source stack (just recipes around a local build). Both run the same control plane; the difference is posture.

fluidbox runs on any conformant Kubernetes cluster with an enforcing CNI — kind, AWS EKS, Google GKE, Azure AKS, DigitalOcean DOKS, or anything else in its support window. fluidbox ships a Kubernetes-native execution provider and an OCI Helm chart. This guide takes you from zero to a certified, run-serving cluster, with the real-world gotchas and costs from a live cloud acceptance.

fluidbox's promise is containment and accountability: hand an agent a repository and a credential, and still be able to answer, afterwards, exactly what it did and why it was allowed to. This page is the map of how that promise is enforced; the threat model and PLAN.md carry the full rationale.

A harness is an agent framework running inside a sandbox. fluidbox ships two — the Claude Agent SDK and Codex — and adding a third is a first-class extension point rather than a fork.

One HTTP surface at /v1, JSON in and out, designed so that the credential you hold determines exactly what you can reach — and so that a record exists for everything you do with it.

fluidbox has four kinds of credential, and they are not interchangeable. Picking the wrong one is the single most common integration mistake, so this page is mostly about which rather than how.

Every endpoint across the four planes — 106 operations generated from the same OpenAPI description you can download above.