<host>-strict
provider. docs/contract/provider-v1.md
documents the provider interface those backends implement; this document is
about standing one up in production. Every command below is derived from the
code cited beside it — anything not verifiable from this repo is marked
“verify for your platform” rather than guessed.
1. Overview
codecalc’s default (local) provider sandboxes with rlimits (Linux/macOS) or
a Job Object (Windows). It is real hardening, but the README says plainly it
is not a hostile-code security boundary — no filesystem, network, or
kernel-level containment. Reach for a strict backend when you intend to run
code you do not trust: an untrusted-input pipeline, a multi-tenant service, a
public-facing tool.
There is exactly one implementation of the strict boundary, and it lives on
Linux: gVisor (runsc) under Docker
(codecalc/strict_runtime.py::DockerGVisorRuntime). Every OS reaches it as
follows:
Without
CODECALC_STRICT_URL set, the <host>-strict provider is still
discoverable (describe() always returns it for the current OS) but it is
an unavailable, fail-closed descriptor: selecting it returns
strict_provider_unavailable and executes nothing
(codecalc/providers.py::NativeStrictExecutionProvider). That is deliberate —
codecalc never silently downgrades a strict request to the unhardened local
path.
2. Linux / gVisor + Docker
This section stands upcodecalc serve-strict — the authenticated HTTP
service that owns the real gVisor boundary
(codecalc/strict_service.py, codecalc/strict_runtime.py). Every other
platform’s strict provider is a client of this service.
Quick start (one command)
scripts/setup-strict.sh automates §2.1–§2.4 below: it checks the
prerequisites (and prints the exact fix if one is missing, rather than
installing anything), pulls the digest-pinned executor image, generates
CODECALC_STRICT_SERVICE_TOKEN if you haven’t set one, and runs the deep
doctor canary against that exact image before it will let you launch.
apt/sudo or installs Docker/gVisor for you — registering
the runsc runtime is still your explicit step (§2.1) — and it never
containerizes serve-strict itself: the service needs the host Docker
daemon to spawn runsc containers, so a socket-in-container setup would only
broaden the attack surface. Safe to re-run. The rest of this section is the
manual reference the script is built from, for auditing or when you need to
deviate from a default.
2.1 Prerequisites
-
Docker Engine, with cgroup v2.
DockerGVisorRuntime.probe()andcodecalc doctorboth readdocker info --format '{{json .}}'and refuse to proceed unlessCgroupVersion == "2"(codecalc/strict_runtime.py::host_prerequisites). -
gVisor’s
runscruntime, registered with Docker under the namerunsc(docker info’sRuntimesmap must contain that key — the runtime name is configurable viaGVisorConfig.runtimebutrunscis the default and what every command below assumes). Installing gVisor itself is outside this repo — verify the exact package and version for your distro against gVisor’s own install docs. On a Debian/Ubuntu host, gVisor’s documented procedure is:Confirm the runtime landed where codecalc looks for it:gVisor’s defaultsystrapplatform needs no KVM (docs/contract/provider-v1.md), so this works on a VM without nested virtualization. Linux x86_64 and ARM64 are both supported; the published image is multi-arch (§2.3).
2.2 The executor image
The strict boundary launches a purpose-built image (docker/executor.Dockerfile: multi-stage, minimal, non-root, tini as
init) carrying codecalc-exec, its --no-net seccomp filter (symbol-shim
fallback), and a python3 runtime.
Two different references matter, and codecalc keeps them deliberately
separate:
-
Diagnostic tag —
codecalc-exec:strict(override withCODECALC_STRICT_IMAGE). This is whatdoctor,check_prerequisites, and the startup canary look for. Build it locally: -
Production image — digest-pinned, published to GHCR, and the only
reference the execution path will run under. Pull it explicitly by the
digest committed in
docker/executor-image.lock:strict_execution_config()refuses to build aGVisorConfig— and the execution path raisesStrictImageUnavailable— if that lock file holds no digest yet (codecalc/strict_runtime.py::published_strict_image,strict_execution_config). It never falls back to the mutable diagnostic tag on the production path. An operator who needs to (re)publish the image dispatches.github/workflows/publish-executor-image.yml(workflow_dispatchonly — it never fires from a push or PR), which buildslinux/amd64andlinux/arm64, pushes toghcr.io/the-40-thieves/codecalc-exec, and commits the resulting digest back intodocker/executor-image.lock.
2.3 What the runtime actually runs
Every strict execution is adocker run your service account should expect
to see on this host. This is not a wrapper script to copy-paste — it is the
exact shape DockerGVisorRuntime.execute() builds
(codecalc/strict_runtime.py), reconstructed here so an operator auditing
the host knows the contract the service holds itself to:
--pids-limitis a host-side task ceiling, and under gVisor that cgroup also holds the sandbox process, the gofer, and the platform’s own threads — none of which exist under plainrunc. codecalc adds a fixed 48-task overhead on top of the caller’s guestprocess_limitso the sandbox has room to boot at all (_GVISOR_HOST_OVERHEAD,codecalc/strict_runtime.py:173-205) — a bareprocess_limit=24alone measured below the boot floor on Cave.- Program stdin (when supplied) never rides the source pipe or argv — it is
written to a private, per-run host temp directory (
0700), the file itself is0644so the gVisor gofer’s guest-uid check can read it, and it is bind-mounted read-only at a fixed guest path distinct from the sandbox’s own tmpfs. - Cleanup (
docker rm --force --volumes) is ownership-verified on every exit path against theio.codecalc.owner/io.codecalc.run-idlabels — it will never remove a container it did not create, even one squatting on the same name.
2.4 Running the service
serve-strict refuses to start without
CODECALC_STRICT_SERVICE_TOKEN set — a token-less bind would expose
gVisor-sandboxed code execution unauthenticated
(codecalc/strict_service.py::main). Every request must carry
Authorization: Bearer <token>, compared constant-time
(hmac.compare_digest); an unauthenticated request gets 401 before any
routing happens.
The service speaks plain HTTP; it does not terminate TLS. A client
(RemoteStrictExecutionProvider) refuses anything except a loopback
http:// URL or an https:// one
(codecalc/providers.py, RemoteStrictExecutionProvider.__init__). Reaching
this service from another host therefore requires an operator-supplied
reverse proxy terminating TLS — put it behind one before binding to a
routable interface, and prefer keeping the bind on loopback and reaching it
through the proxy rather than binding a routable interface directly.
At startup the service best-effort reconciles containers a crashed previous
generation may have leaked (§5) before it starts accepting new runs.
3. Windows / AppContainer
This is a different mechanism from §2 and §4: it hardens the local provider in-process on the Windows host itself, rather than delegating to a Linux service. It is not registered under thewindows-strict descriptor —
that descriptor is either the fail-closed stub or, with CODECALC_STRICT_URL
set, a client of the Linux service exactly as in §4. AppContainer hardening
is an independent, complementary opt-in on the default backend.
3.1 Enabling it
CreateAppContainerProfile, no capability SIDs — no network) created fresh
per run (executor/src/platform/windows.rs::create_appcontainer,
prepare_appcontainer).
3.2 What it grants, and to whom
Two different grants, deliberately split:-
The run’s own sandbox workdir — full access (
GENERIC_ALL), granted to this run’s own AppContainer SID only, inheritable so files the payload creates are covered (windows.rs::grant_sid_path_access). Concurrent runs cannot reach each other’s workdirs. -
The interpreter’s own directory tree — read+execute, granted to the
fixed, well-known “ALL APPLICATION PACKAGES” SID (
S-1-15-2-1), which every AppContainer is a member of (windows.rs::all_application_packages_sid). This grant is per-node and non-inheritable — measured on real Windows 11, an inheritable ACE (however applied:SetNamedSecurityInfoW,TreeSetNamedSecurityInfoW, evenicacls /T) never reaches an interpreter’s pre-existing, inheritance-protected files, sogrant_tree_explicit_readwalks the tree and applies an explicit ACE to every file individually. This walk runs once per interpreter, not once per execution: a marker keyed by the interpreter’s own size+mtime is cached under%LOCALAPPDATA%\codecalc\ac-granted\(windows.rs::ac_grant_marker,ensure_interpreter_ac_readable). A several-thousand-file interpreter tree is walked on first use and never again until the interpreter itself changes. The trade-off this leaves: a read-only ACE, readable by any AppContainer on the machine, sits on a public interpreter’s files — acceptable because those files carry no secrets, and the alternative is a full tree walk on every single execution.
3.3 Prerequisites and least-privilege notes
- No Docker, no runsc, no external service — the boundary is native Win32
APIs (
CreateAppContainerProfile,SetEntriesInAclW,SetNamedSecurityInfoW). - Fails closed. If profile creation, SID derivation, or an ACL grant
fails, the launch is refused outright rather than dropping to an
unconfined process (README, “Sandbox guarantees” / AppContainer section;
windows.rs::prepare_appcontainerpropagates every error). - The interpreter grant needs write access to
%LOCALAPPDATA%\codecalc\for its cache marker, and read access to the interpreter’s own directory tree to perform the initial grant — run the service account with those, not with broader filesystem rights. - Disclosed as unverified, every run. CI has no way to exercise
AppContainer behavior (server SKUs can’t), so every strict-hardened
Windows run still carries
appcontainer_isolation_unverified_on_windowsinunenforced, even though the isolation has been independently verified by hand on a real Windows 11 box (AppContainer SID present, user-profile secrets unreadable, writes confined to the workdir, network denied). Treat that string as this repo’s honest limit, not a defect — it says “we could not prove it from CI,” not “it does not work.” - If you need the CI-verified gVisor boundary instead of this native one,
configure this Windows host as a client of §2’s service via
CODECALC_STRICT_URL(§4’s configuration applies identically here).
4. macOS / remote-Linux provider
macOS has no local strict primitive. The only strict path isRemoteStrictExecutionProvider — an authenticated client of a Linux host
running the §2 service (codecalc/providers.py).
This is not a gap this document works around locally, because there is no
local container option that would actually close it: gVisor itself “requires
Linux” (https://gvisor.dev/docs/user_guide/faq/, retrieved 2026-09-07), and a
macOS/Windows container runtime that could host it — Podman included —
“requires a virtual machine” underneath
(https://docs.podman.io/en/latest/markdown/podman-machine.1.html, retrieved
2026-09-07), i.e. it would still be a remote-to-this-process Linux boundary,
just a locally-hosted one. Even without gVisor layered on top, a bare
container runtime is a weaker, incomplete boundary on its own — Docker’s own
security docs and Kubernetes’ multi-tenancy docs say so of their respective
defaults (cited in SECURITY.md’s “Known limitations”). §1’s decision stands
unchanged: the strict boundary is gVisor+Docker on Linux, reached remotely
from anywhere else, not a locally-approximated substitute.
4.1 Configuration
codecalc/providers.py::configured_registry). Without CODECALC_STRICT_URL
set, macos-strict is registered as the fail-closed stub (§1) instead — it
is never silently absent, but it never silently runs unhardened either.
4.2 The plaintext-endpoint rejection
RemoteStrictExecutionProvider.__init__ parses CODECALC_STRICT_URL and
raises ValueError at construction — before any request is sent — unless
the scheme is https://, or the scheme is http:// and the host is
a loopback address (127.0.0.1, ::1, localhost). Any other plaintext
endpoint is refused outright:
user:pass@ credentials — those
belong in CODECALC_STRICT_AUTHORIZATION, not the URL, so they cannot end
up serialized somewhere the URL does.
4.3 The health handshake before any source is sent
Before submitting code, the client requiresGET /v1/health to report a
compatible interface_version, ready: true, strict: true,
isolation_profile: "gvisor-v1", and every one of application_kernel,
cgroup_v2, namespaces, seccomp, read_only_rootfs, non_root,
capabilities_dropped, filesystem, network, descendants, and
resource_limits as enforced
(codecalc/providers.py::RemoteStrictExecutionProvider._verified_health).
Any gap fails with strict_attestation_failed and the execution endpoint is
never called — a source snippet never leaves the Mac against a boundary that
did not attest fully. Each successful execution must repeat the same
controls in its own receipt, verified again on the way back.
Both CODECALC_STRICT_AUTHORIZATION and the bare credential inside it are
redacted from every error, descriptor, and result this provider returns.
5. Operations
5.1 Startup and pre-flight checks
doctor --deep promotes strict_runtime.check_prerequisites() from a cheap
docker info + image-presence check to a real startup canary
(codecalc/strict_runtime.py::_startup_canary): it launches the image with
the same defensive flags a real run uses (no network, read-only root,
dropped capabilities, non-root, no-new-privileges, bounded memory) and reads
the runtime the daemon actually recorded, not a string the payload printed.
Transient gVisor boot flakes (cannot read client sync file, failed to create shim task, an I/O error building the root filesystem) are retried up
to four times before being reported as real failures — run this after any
host change (kernel update, Docker upgrade, gVisor upgrade) and before
trusting the boundary in production.
5.2 Orphan recovery
A crashedserve-strict process can leak containers it never got to clean
up. DockerGVisorRuntime.recover_orphans() runs automatically at service
startup, before any new run is admitted
(codecalc/strict_service.py::main): it enumerates containers carrying
codecalc’s io.codecalc.owner label, re-verifies ownership on each one
individually (a container whose label changed between the list and the
look — a squat, a race — is left untouched), and force-removes the rest.
Enumeration failing is itself fail-closed: the service refuses to start
serving rather than silently reporting a clean host it could not actually
prove clean.
You do not need to run this by hand in the ordinary case — restarting the
service is enough. If you want to check it worked, serve-strict’s stderr
names how many containers it recovered on startup.
5.3 Fail-closed behavior, by cause
None of these fall back to unhardened execution. A strict request that
cannot be proven safe is refused, never silently downgraded.
5.4 Quota and limit tuning
What a caller of the remote service can actually move, versus what is fixed:max_cpu is now forwarded end-to-end, closing the gap this section used to
flag. process_limit’s “No” is fixed-by-design rather than a gap: there is
no wire knob for it, so a deliberate limit — not an oversight — keeps it at
the runtime’s built-in default.
Cross-referenced from the top-level
README.md
and from docs/contract/provider-v1.md.