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 at the end of this page, and in the grading contract. Read those before estimating.

For the operation-by-operation contract, see Sandbox provider contract. For what your provider can and cannot claim about isolation, see Provider grading and honest limits.

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

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.

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.

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 — 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 — why a third party pins to advisory_filter, and the exact cost of putting a process behind a network hop.
• 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 — the harness-side author contract this one is modeled on.