> ## Documentation Index
> Fetch the complete documentation index at: https://checkfu.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Sandbox providers
> What a sandbox provider is, what Checkfu supplies versus what you supply, and the capability envelope you must advertise honestly.
Checkfu is harness-agnostic and sandbox-opinionated. Any CLI or ACP image can become a harness
through a published contract, a self-serve `checkfu harness test oci` diagnostic, and a
server-run `checkfu harness verify` that issues signed conformance evidence. The machine that
harness executes **inside** has, until now, only ever been implemented in-tree: Docker, E2B,
Daytona, and a host-process tier on the customer Runner, plus Cloudflare containers and the
same cloud vendors on the Worker-hosted runner. Every one of them was written by Checkfu. This
page is the first half of the contract that opens that seam to a third party.
**This seam is not yet callable by a stranger.** The provider contract is stable and
documented here as it exists in the Runner today, but the wire form, the enrollment path,
the self-serve conformance command, and two server-owned ceilings are in-flight. The exact
gaps — and which of them block publication — are named in
[Publication readiness](#publication-readiness) at the end of this page, and in the
[grading contract](/concepts/sandbox-provider-grading). Read those before estimating.
For the operation-by-operation contract, see
[Sandbox provider contract](/concepts/sandbox-provider-contract). For what your provider can
and cannot claim about isolation, see
[Provider grading and honest limits](/concepts/sandbox-provider-grading).
## What a sandbox provider is
A sandbox provider **materializes, holds, and reclaims the isolated machine a Run executes
in.** It is the counterpart to a harness, not a variant of one:
| | Harness | Sandbox provider |
| ------------- | --------------------------- | ----------------------------------------------- |
| Supplies | the agent loop | the machine the loop runs in |
| Ships as | an OCI image Checkfu runs | a service Checkfu drives |
| Speaks | ACP or the one-shot floor | the provider lifecycle contract |
| Runs as | workload inside the sandbox | infrastructure outside it |
| Trust posture | untrusted workload code | untrusted **statement**, trusted **allocation** |
That last row is the whole design. A harness is code Checkfu is willing to execute under
confinement. A provider is a party Checkfu asks to *create* the confinement — so nothing it
says about that confinement can be taken as proof, while everything it allocates must still be
reclaimable. The contract is built around that asymmetry: every value a provider returns is
decoded and cross-checked against state the Runner already holds, and every allocation carries
a cold compensation the Runner can invoke without trusting the value it is compensating.
## Where a provider sits
A Run reaches a provider through three hops, and only the last one is yours:
1. **Admission** (control plane). The Session's SandboxProfile freezes at admission and never
moves again: `tier`, `base_image`, `packages`, `network_policy`, `resource_limits`, and
`retention_mode`. Mounts are the other freeze horizon — they re-resolve at each Run start
and are fixed within the Run — so they arrive on the provision request rather than inside
the profile, alongside the attempt's `platform` and `root_image`. Either way, a provider
never sees a request the control plane did not already admit.
2. **Selection** (Runner). The Runner picks exactly one adapter whose advertised
`(provider, provider_revision, materialization_revision, placement)` tuple matches the
attempt's execution target, then checks the profile against that adapter's capability
envelope. A requirement the envelope does not meet fails **before any provider work
starts**, as a typed `SandboxCapabilityUnavailable`.
3. **Execution** (your provider). The Runner drives the lifecycle contract, decoding and
validating every result.
Selection is exact, not best-effort. Two adapters matching the same tuple is
`SandboxAdapterAmbiguous`; zero is `SandboxAdapterUnavailable`. Neither falls back.
## What Checkfu supplies versus what you supply
| Concern | Who owns it |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Session identity, event log, settlement, billing | Checkfu control plane |
| Admission: which profile, which image digest, which limits | Checkfu control plane |
| Model credentials and the model gateway | Checkfu control plane — the sandbox never holds a provider key |
| Run-scoped capability tokens (`cfu_run_*`) | Checkfu control plane; lease-fenced and safe to hand to an adversarial sandbox |
| Lease fencing `(lease_id, lease_epoch)` and orphan reconciliation | Checkfu Runner |
| Mount plans **and mount bytes** — the Runner reads Project and Git content itself and pushes it in through `writeFile` | Checkfu Runner |
| Result decoding, identity cross-checks, path admission, bound enforcement | Checkfu Runner |
| Compute, isolation, filesystem, process lifetime | **You** |
| Materializing the derived image from the admitted profile | **You** |
| Accepting staged writes and making those paths real before activation | **You** |
| Snapshot bytes, their custody, and their expiry | **You**, if you advertise snapshots |
| The network the sandbox sits on | **You**, on day one — see [Network posture](#network-posture) |
The mount row is worth reading twice, because it is cheaper than it sounds. You do **not**
fetch from Projects, Git, or any Checkfu store, and you hold no credential for any of them.
The Runner resolves every mount file, verifies its digest, and hands you the bytes through
ordinary `writeFile` calls during `provisioning`. That is what the conformance case "stages an
immutable Git blob **without a sandbox credential**" exists to prove.
The line is drawn so that a provider is replaceable. Nothing on the Checkfu side of the table
changes when the provider changes: the capability envelope
(`capabilityEnvelopeForDriver`) that decides `model_control` and `usage_authority` takes the
driver version and retention mode and **does not take the sandbox provider at all**. Swapping
your provider in cannot change what the platform enforces or observes about model use.
## The capability envelope
Every provider advertises one `SandboxProviderCapabilities` value. It is the only thing
selection knows about you, so it is also the only thing you can get wrong before a Run ever
reaches you.
| Field | Meaning | Fail-closed default |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `provider` | your coordinate, `^[a-z0-9][a-z0-9._-]{0,254}$` | required |
| `provider_revision` | opaque identity of this exact implementation | required |
| `materialization_revision` | opaque identity of how you turn a profile into an image | required |
| `placement` | `test` \| `local` \| `hosted` \| `byoc` | required |
| `tiers` | `container` and/or `microvm`; non-empty, unique | required |
| `platforms` | `{os, architecture}` pairs; `os` is always `linux`, `architecture` is `amd64` or `arm64`; non-empty, unique | required |
| `image_mode` | `profile` (you build from the admitted profile) or `fixed` | required |
| `fixed_base_images` | non-empty exactly when `image_mode` is `fixed` | required |
| `package_managers` | which of `apt cargo gem go npm pip` you can materialize | required |
| `network_modes` | `none` \| `allowlist` \| `unrestricted`; non-empty, unique | required |
| `retention_modes` | `durable` and/or `ephemeral_zdr`; non-empty, unique | required |
| `snapshots` | whether you can snapshot, clone, and resume | required |
| `snapshot_custody` | `runner` (bytes die with the Runner host) or `provider` | `runner` |
| `enforcement` | the nine-axis authority statement — see below | required |
| `egress_certification` | your D130 egress grade | `unsupported` |
| `list_dir` | whether you can enumerate a mounted tree | `false` |
| `minimum_resources` / `maximum_resources` | the ordered envelope you accept | required |
| `max_mounts` | how many mounts you accept; any non-negative integer, but `64` is the effective ceiling because a provision request may not carry more | required |
Three cross-field rules are enforced at decode, not at run time:
* `image_mode: "fixed"` and a non-empty `fixed_base_images` must agree.
* `retention_modes` including `durable` requires `snapshots: true` — a durable Session needs a
Checkpoint, and a provider that cannot snapshot cannot serve one.
* `snapshot_custody: "provider"` requires `snapshots: true`.
The three optional fields default *downward*. An envelope that omits `list_dir`,
`snapshot_custody`, or `egress_certification` decodes to the weakest legal value. This is
deliberate: an older envelope keeps its exact old meaning, and silence is never read as a
capability claim.
### The enforcement statement
`enforcement` is nine isolation axes, each carrying **who** realizes it:
`sandbox_isolation`, `root_read_only`, `non_root`, `no_new_privileges`,
`capabilities_dropped`, `mounts_sealed`, `disk_limit`, `network_policy`, `resource_limits`.
Each takes one of four authorities:
| Authority | Means | Counts as enforcement |
| ------------------- | ------------------------------------------ | --------------------- |
| `runner_enforced` | Checkfu's own trusted code set the control | yes |
| `provider_attested` | the provider says it set the control | yes |
| `guest_observed` | read from inside the guest | **no** |
| `not_enforced` | the control is not applied | **no** |
`guest_observed` is diagnostic only. A guest can report what it likes; observing a value from
inside the confinement cannot prove the guest was prevented from changing it. `not_enforced` is
honesty, never enforcement — declaring it is correct behavior, not a defect.
The in-tree providers show the range. Docker declares `runner_enforced` on all nine, because
the Runner itself sets the container flags. E2B declares `provider_attested` for isolation,
disk, network, and resources; `runner_enforced` for `mounts_sealed`; `guest_observed` for
`non_root`; and `not_enforced` for `root_read_only`, `no_new_privileges`, and
`capabilities_dropped`. That envelope is not E2B failing — it is E2B being accurate.
**A third-party provider may not claim `runner_enforced` on any axis.** By construction you
are not the Runner. `runner_enforced` means "Checkfu's own code set this," and it is the
authority a per-process evidence cross-check is measured against. Today the server-owned
enrollment ceiling that would refuse this claim **does not exist** — `enforcement` is not a
field of `RunnerProviderCapability`, so no ceiling intersects it. That is the single largest
open blocker on publishing this seam; see
[the grading contract](/concepts/sandbox-provider-grading#the-enforcement-ceiling-gap).
### Advertise honestly, and expect to be exercised
Declaring a capability you do not serve is worse than not declaring it. Every field above is a
selection input, so a false claim does not degrade — it routes work to you that you cannot do,
and the failure surfaces mid-Run instead of at selection.
The precedent is already in the product. Checkfu ships a `host-process` tier that runs the
harness as a bare OS process with the host's own network and no confinement worth the name.
It was not refused; it was made **loud**. It advertises `network_modes: ["unrestricted"]`
only, so no `none` or `allowlist` profile can ever be admitted to it. It advertises no
snapshots, no mounts, no package materialization, and `durable` retention only, because a
shared host disk cannot attest zero data retention. It declares exactly the three lifecycle
assurances it actually implements and `false` for the two it does not.
That is the standard for a partner envelope: the weak tier is allowed, the *quiet* weak tier
is not.
## The day-one tier
The program's estimate for a first partner provider is a deliberately narrow tier:
* `retention_modes: ["ephemeral_zdr"]` — no durable Sessions, so no snapshot, clone, or
resume, and `release` always destroys.
* `snapshots: false`, `list_dir: false`.
* `network_modes: ["none"]` — the plane route to the model gateway persists; there are no
**workload** destinations.
* `egress_certification: "unsupported"`, which is honest at `none` and is the only grade
consistent with naming no destination selector.
It also declares no `readFiles`, no enumeration, and no `openProcess`, which confines it to
one-shot harnesses with no writeback or capture. Against the conformance suite it records
**four skips of nine** — the three cases requiring `snapshot` and the one requiring
`network-allowlist`. The other five run and must pass.
| Tier | Adds | Estimate |
| ------------- | ------------------------------------------------------------------------------ | ------------------ |
| Day one | — | 12–15 partner-days |
| Durable | snapshots, clone, resume, enumeration | 25–30 |
| Docker parity | physically-contained file reads, `allowlist` egress, provider snapshot custody | 38–45 |
None of those figures includes `openProcess`, and `security_boundary` is not in any of them: it
is not reachable by implementation effort at all, only through a matrix Checkfu runs. See
[the grading contract](/concepts/sandbox-provider-grading).
Public documentation names this tier as what it is. A partner provider on the day-one tier is
not "Checkfu with a different backend"; it is a narrower product surface, and the capability
envelope is what says so.
## Network posture
**Default: you supply your own network.** Checkfu does not publish or ship its model-relay and
egress-guard images to partners, and a partner provider is not expected to run them.
What that costs was measured rather than assumed, and the answer is smaller than it looks:
* **Model-credential custody is unaffected.** The relay holds no provider secret. The token it
authenticates is a Checkfu-minted, lease-fenced `cfu_run_*` capability that the sandbox
already holds in its own environment; the real provider key lives in the control plane,
three trust boundaries away. The model gateway authenticates bearer possession plus a live lease —
there is no source-IP check, no mTLS, and no property of the relay anywhere in that path.
* **Usage metering is unaffected.** Accounting happens in the control plane on the model-gateway
request path. The relay counts nothing and touches no ledger.
* **What is genuinely lost** are three defense-in-depth properties, none of which is a custody
or metering guarantee: request/response **header narrowing** to a fixed allowlist,
**plane-path narrowing** to five path shapes, and a **second expiry clock** ahead of the
model gateway's own. The last two duplicate authorizations the model gateway already enforces. None of
the three is expressible in `SandboxProviderCapabilities`, and none is present in E2B today
either.
* **The architectural path to `security_boundary` is lost**, not a present capability. That
grade requires an owned matrix regardless, and a third-party provider is pinned to
`advisory_filter` whether or not it runs Checkfu's guard.
Credential substitution — rendering a secret into a workload request at the egress edge — is
**not** part of this contract and is not foreclosed by it. It is vacuous at
`network_modes: ["none"]`, since there is no destination to bind a credential to, and Checkfu's
current egress edge is a CONNECT proxy that never terminates TLS and structurally cannot inject
anything at any mode. Both shapes that could support it later — a TLS-terminating edge, or the
control plane's existing forward-only credential custody — live outside the provider seam.
## Publication readiness
Stated plainly, because the gap between "documented" and "callable" is the thing a partner
needs to know before estimating.
**Stable enough to build against today:**
* The lifecycle contract's seventeen members, their arguments, and their result shapes.
* The capability envelope, its cross-field rules, and its fail-closed defaults.
* The identity cross-checks the Runner applies to every returned instance, snapshot, clone,
and release.
* The closed error vocabulary and which condition produces which member.
* The nine-case conformance suite's *content* — the behaviors that will be graded.
* The grading rule: third-party providers pin to `advisory_filter`.
**In flight, and named as such wherever it appears in these pages:**
| Gap | Status |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The wire form of the sixteen lifecycle members | Designed against existing in-repo patterns; no schemas, no vectors, no endpoints |
| The `openProcess` wire | Designed and spiked end to end; `out_end`/`err_end` and the credit `window` frame specified but unbuilt |
| Machine-readable author kit (JSON Schemas + golden vectors) | Not started; the harness equivalent is the model |
| A self-serve conformance command | The nine cases exist as an in-tree test port; there is no partner-runnable command |
| Provider enrollment | Capability *declaration* already enrolls through the Runner claim request against a server-owned ceiling; provider *code* cannot be admitted at all, because each transport hands the runtime a compiled-in adapter |
| The `enforcement` ceiling | **Blocking.** No server-owned ceiling intersects a provider's enforcement statement |
| The `egress_certification` ceiling | **Blocking.** The grade is compared Runner-locally and is not carried on `RunnerProviderCapability` |
The two blocking rows are the same defect in two places: a capability that is meaningful only
because Checkfu authored it becomes self-assertion the moment a stranger authors it. Publishing
the seam before those ceilings land would ship a weak tier that nothing in the system records
as weak — which is the exact failure the host-process tier was designed to avoid.
## Next steps
* [Sandbox provider contract](/concepts/sandbox-provider-contract) — every operation, what it
must do, what is optional, and what happens when an optional capability is absent versus
wrong.
* [Provider grading and honest limits](/concepts/sandbox-provider-grading) — why a third party
pins to `advisory_filter`, and the exact cost of putting a process behind a network hop.
* [Security](/concepts/security) — the threat model the sandbox sits inside, and how a
SandboxProfile's network policy differs from a Connection's egress rules.
* [Harness wire extensions](/concepts/harness-extensions) — the harness-side author contract
this one is modeled on.