1.0.0
This is the protocol-neutral boundary between CodeCalc and an execution
backend. MCP, HTTP, CLI, and library adapters compile their inputs into a
ComputationSpec; providers return CodeCalc’s existing execution-result
contract. Transport types do not cross this boundary.
This document is the interface a provider implements. For provisioning and
running a strict backend in production — the Linux gVisor+Docker host,
Windows AppContainer hardening, and configuring a macOS/Windows client of the
remote service — see the operator runbook at
docs/deployment/README.md.
Request
ComputationSpec contains the language, source, stdin, timeout, optional
working directory, memory/output/CPU ceilings, and network policy. New request
fields must have defaults so an older provider can reject an unsupported
capability explicitly rather than misinterpreting a request.
Provider descriptor
Every provider publishes a JSON-serializable descriptor containing:interface_version: version of this interfaceprovider_id: stable selection keyprovider_version: provider implementation versionhost_class: local, region, or other placement classstrict: whether the provider claims a security boundary for hostile codecapabilities: boolean support declarations
execute, managed_runs, inspect, stream, cancel,
cleanup, files, artifacts, sessions, health, runtime_discovery, and
workdir, and network_control. Callers must not infer support from provider
identity.
managed_runs=true means the provider receives CodeCalc’s run ID before the
payload starts, so later inspection, cancellation, and cleanup target the same
owned workload rather than an unrelated provider-generated ID.
Required operations
All providers implementdescribe(), health(), list_runtimes(),
execute(spec), and async execute_stream(spec, on_progress=...). Health reports an explicit readiness boolean and runtime
discovery returns JSON-serializable entries. Optional operations remain present
on the interface so their failure is uniform: inspect, stream, cancel,
cleanup, collect_artifacts, list_files, and create_session. Calling one
that the descriptor marks false raises UnsupportedCapability with the stable
provider error code unsupported_capability; CodeCalc must never silently
route that operation to a weaker provider. A provider advertising stream=true
executes the canonical spec and may invoke the protocol-neutral progress
callback; transport objects such as MCP contexts never cross this boundary.
Provider selection is explicit or uses the configured default. An unknown
explicit ID returns a validation result carrying provider_error set to
unknown_provider; it never falls back.
The execution receipt
Every successful execution result carries aprovider object — the execution
receipt — versioned by its own receipt_version (currently 1.2.0) so a
reader can tell “this receipt predates source hashes” from “this run had no
source”, which are not the same fact. MAJOR removes or retypes a key, MINOR adds
one, PATCH changes descriptions only.
The capability broker (capabilities)
The capabilities block records what the capability broker decided for a run.
Its one load-bearing invariant is that approved never exceeds requested:
policy may narrow the capabilities a job asked for, never add to them.
Brokering runs on the same footing for a synchronous
execute_code and a
background run_submit: run_submit decides and enforces before the run starts,
so a policy cannot be bypassed by moving a job to the background — an escalation
or strict-unenforceable job is rejected before any background work, and an
enforced run’s run_inspect receipt carries the same capabilities block.
Brokering is off by default. CODECALC_CAPABILITY_POLICY unset (or empty)
runs exactly as before — the block still reports the four sets with
approved == requested and brokered: false, but nothing is denied and nothing
is rejected. When the variable is set, comma-separated directives configure it:
deny-network— flip the default to network-denied. The broker treats a capability as enforceable when the provider’s descriptor says it supports control over that capability (network_control,truefor the native executor backend only when the Rust binary is in use AND this host can enforceno_netin the kernel — Linux, with the real no_net seccomp-bpf program actually installable, verified at startup by forking a disposable child that attempts the install and reports whether the kernel accepted it (executor/src/platform/unix.rs’sseccomp::installable), not merely thatPR_GET_SECCOMPsays seccomp is configured — a kernel withCONFIG_SECCOMP_FILTER=n, or an inherited policy denyingPR_SET_NO_NEW_PRIVS, would pass the weaker check while the real install still fails. It isfalseon the same Rust binary when only the best-effort, bypassable LD_PRELOAD/dyld symbol shim would hold: macOS, or a Linux kernel without an installable seccomp filter; the shim cannot itself enforce a denial, only apply it on a best-effort basis, andnetwork_controlno longer claims otherwise). Where the provider reports support, the job runs withno_netforced on. Where it does not (no native executor, or a native executor without kernel enforcement), a non-strict policy leaves the request as-asked and discloses the leak —networkstays ineffective— rather than forcing ano_netthe provider would silently ignore or, like Piston, reject outright. Combine withstrictto reject an unenforceable denial instead of disclosing it.allow-network— explicitly grant network. Honoured only for a job that requested network; granting network to a job that asked for none is an escalation the broker rejects.strict— reject a job outright when a capability’s brokered DENIAL cannot be enforced by the selected provider, rather than run with a denial the sandbox would silently leak.
permission_denied with a
provider_error of capability_not_requested (escalation) or
capability_unenforceable (strict, no enforcement available), refused before any
side effect. Broker decisions and other security-relevant side effects (a denied
capability, a refused install, a cleanup) are appended to an audit stream at
~/.codecalc/audit/audit.log (relocate with CODECALC_AUDIT_LOG, disable by
setting it empty); each event carries a source-safe timestamp, the run/session
id, the decision and its reason, and never the executed source or a credential.
The limits receipt records the canonical requested values, the controls the
provider reports as enforced, and the exact unenforced disclosures returned
with the result. “Provider reported” is deliberate: CodeCalc preserves the
backend’s enforcement claim; it does not independently attest to a remote host’s
configuration.
determinism reports what it observed and names what it did not. Every input
appears either with a value or in unrecorded — never as a bare null, because
an unexplained null reads identically to “the value was empty” and to “this key
was never populated”. Three facts are stated rather than smoothed over:
TZis not in the executor’s environment allowlist, so the child inherits the host’s system zone and CodeCalc cannot name it.timezoneis unrecorded rather than guessed from the server’s own zone, which describes a different process. AddTZto the allowlist and this populates itself — the block is read back out ofexecutor._env(), not transcribed from it.- CodeCalc has no seed concept: no tool accepts one and no runtime is seeded.
seedisnullon every run and says why. - Only the
localprovider runs through CodeCalc’s own sandbox. For any other,sourceisprovider_ownedand nothing is reported, because this server’s locale is not the locale of a run that happened on someone else’s host.
workdir enters only through spec_hash, never as text, and the
determinism block reads exactly three names out of the forwarded environment
rather than copying it, so PATH and HOME cannot ride along.
Compact results retain the actionable half — receipt_version, provider_id,
spec_hash and the whole limits object — and name the descriptive keys they
dropped in receipt_detail. Copying the receipt wholesale grew a compact result
by 69%, which defeats the mode it rides in; the split follows the same rule
already applied to unenforced.
Cross-provider verification executes the same immutable ComputationSpec
independently through two explicitly selected providers. It compares semantic
result fields (ok, verdict, stdout, stderr, and exit code), excludes timing and
resource telemetry from agreement, and retains both provider receipts.
Included providers
local wraps the existing Rust executor or Python fallback. It remains the
default and requires no configuration. It advertises streaming: the native
executor reports partial stdout through the progress callback, while the
Python fallback completes synchronously and returns streamed=false with an
explicit note rather than pretending it emitted progress.
piston targets the open-source Piston v2 HTTP API. It is registered only when
CODECALC_PISTON_URL contains an absolute HTTP(S) base URL; CodeCalc has no
default public endpoint. CODECALC_PISTON_AUTHORIZATION, when set, is copied
only to that provider’s Authorization header. Both the complete header value
and its credential portion are redacted from normalized results.
Piston’s synchronous /api/v2/execute surface supports execution and resource
limits but not run inspection, streaming, cancellation, sessions, artifact
retrieval, or caller-selected working directories. Those capabilities are
advertised false and fail with UnsupportedCapability. Network isolation is a
Piston server setting rather than a per-request control, so no_net=True also
fails explicitly instead of assuming the remote deployment’s configuration.
Piston’s output ceiling is likewise server-wide rather than request-scoped;
CodeCalc applies a requested max_output_kb to the returned buffers, classifies
overflow as OLE, and records
max_output_kb_enforced_after_provider_response in unenforced so this
post-response protection is never presented as remote resource enforcement.
Piston’s timeout is also applied per phase, so compile plus run can total
twice the caller’s budget. CodeCalc checks that total after the response: when
compile.wall_time + run.wall_time exceeds timeout * 1000, the result is
TLE in phase run with timed_out: true, keeping the output Piston returned.
For a compiled language the adapter also records
timeout_enforced_after_provider_response in unenforced (contract 1.19.0),
so the after-the-fact check is not presented as a remote deadline.
Piston health converts connection/JSON failures into ready: false; execution
converts them into a rejected result with
provider_error="provider_transport_failure". Both paths redact configured
authorization material before returning data to an adapter.
The Piston adapter reports backend="python" in the version-1 result envelope
because that closed field identifies CodeCalc’s adapter implementation. The
independent provider receipt identifies provider_id="piston"; adding Piston
to the closed backend enum would break strict version-1 schema validators.
<host>-strict is always discoverable for the current client OS. Without
CODECALC_STRICT_URL it is an unavailable, fail-closed descriptor: selecting
it returns strict_provider_unavailable and executes nothing. With an explicit
URL it becomes an authenticated adapter to CodeCalc’s Linux strict execution
service. CODECALC_STRICT_AUTHORIZATION is sent only in the Authorization
header and is redacted from errors and metadata.
Before sending source, the adapter requires /v1/health to report a compatible
provider interface, ready=true, strict=true, isolation_profile=gvisor-v1,
and all of application_kernel, cgroup_v2, namespaces, seccomp,
read_only_rootfs, non_root, capabilities_dropped, filesystem, network,
descendants, and resource_limits as enforced. Missing controls produce
strict_attestation_failed; the execution endpoint is never called. Each
successful execution must repeat those controls in its receipt. Managed run
IDs are used in execute, inspect, cancel, and cleanup paths.
The Linux service profile uses a digest-pinned executor image under Docker’s
explicitly registered gVisor runsc runtime. It supports Linux x86_64 and
ARM64; gVisor’s default systrap platform avoids requiring KVM. Landlock may
still harden local execution, but it is not evidence for the gVisor boundary.
Boundary evidence, and what is measured where
The executor image is built bydocker/executor.Dockerfile (multi-stage,
minimal, non-root, tini as an init so codecalc-exec is never PID 1) and
carries codecalc-exec plus its blocknet.so shim and a python3 runtime.
scripts/build_executor_image.sh builds it locally; scripts/gvisor_conformance.sh
builds it and runs the hostile-workload conformance. For the PRODUCTION execution
path the image is published to GHCR and pinned by digest — see the image-residual
note below.
What is PROVEN, on a runsc-capable host (measured on Cave, Docker 29.7.2 + runsc,
ARM64), by tests/test_gvisor_conformance.py:
- The workload genuinely runs under
runsc, confirmed OUT OF BAND bydocker inspect .HostConfig.Runtime— never a string the payload printed. - A fork bomb is bounded by
--pids-limit; the container terminates, is not OOM-killed, and leaves no host processes. - A memory bomb is OOM-killed by the cgroup memory limit (exit 137), not the host.
- A descendant tree is entirely destroyed on cancellation — no leaked host processes or containers.
- Egress is blocked by
--network=none; filesystem writes outside the bounded tmpfs are blocked by the read-only root with no host bind.
codecalc doctor (and the strict service at startup) call the runtime’s host
probe and surface these prerequisites; doctor --deep adds a real startup
canary. DockerGVisorRuntime.recover_orphans() reconciles owned orphan
containers by their immutable run-identity label; it is invoked by the remote
strict execution service (which lives out of this repo) at that service’s
startup, not by codecalc itself.
Published, digest-pinned image (image residual — CLOSED, operator-gated)
A registry-published, multi-architecture, DIGEST-PINNED image is now produced by thepublish-executor-image workflow. One operator workflow_dispatch:
- builds
docker/executor.Dockerfileforlinux/amd64ANDlinux/arm64(buildx + QEMU) and pushes it toghcr.io/the-40-thieves/codecalc-exec(lowercase org, GHCR), authenticated with the built-inGITHUB_TOKENandpackages: write— no external secret; and - commits the immutable index digest into
docker/executor-image.lockasghcr.io/the-40-thieves/codecalc-exec@sha256:<digest>, pushed back to the branch.
published_strict_image() reads that lock as the production default;
strict_execution_config() builds the GVisorConfig from it. When the lock holds
no digest yet (placeholder/absent — the shipped state until the first dispatch),
the execution path fails closed with StrictImageUnavailable (“no published
strict image; run the publish-executor-image workflow”), never falling back to the
mutable local tag. GVisorConfig still refuses a mutable reference outright.
strict_image() keeps the local codecalc-exec:strict tag for DIAGNOSTICS
(doctor, check_prerequisites, the startup canary), which do not require a digest.
What still requires the operator: the first workflow_dispatch — the real
multi-arch push and the first committed digest happen only then (there is no
push/PR trigger), and until it runs the production execution path is fail-closed.
RESIDUALS, stated plainly:
- GitHub CI cannot exercise this: hosted runners have no
runsc, so the conformance suite SKIPS there (green, with a printed reason). It is proven on Cave / a runsc host, not on GitHub runners. --pids-limitunder gVisor bounds HOST-side tasks (the sandbox and gofer count too), so the process limit must leave headroom for gVisor’s baseline (~48 is the floor on Cave); a runc-appropriate limit of 24 is too low for the sandbox to start.
Versioning policy
The interface uses semantic versioning independently of the execution-result contract:- MAJOR: removes or changes an operation, field, capability meaning, or error behavior.
- MINOR: adds an optional capability, descriptor field, or request field with a backward-compatible default.
- PATCH: documentation and implementation corrections that do not change the provider wire or call contract.