codecalc — universal code & logic calculator for AI models

codecalc is an offline, self-hosted MCP server that gives an AI agent a calculator, a code runner, and a logic checker — so it gets a correct answer instead of a guessed one. It runs code in 31 languages, does exact symbolic math, solves SMT/logic problems, and measures complexity, all exposed as 52 MCP tools.

Three things nobody else offers together cleanly:

• Offline-core — ships no model, no API key, no gateway, no telemetry. The core opens no sockets; network access is opt-in and only where a specific tool's job needs it (the Piston provider, install_package, the runtime-update tools, executed code unless no_net, and a one-time in-process grammar download on first analyze_complexity — full breakdown in the network-boundary table below).
• Safe execution of untrusted code — an opt-in strict isolation boundary (gVisor+Docker on Linux, AppContainer on Windows) layered above the default rlimit sandbox, fail-closed and attested.
• Verification tools — verify_translation proves a port to another language behaves identically, verify_optimization proves an optimization preserved behavior, and z3_check proves or refutes logic with an SMT solver.

When to use codecalc

Use it when you want a free, local, private, hardened code-runner and verifier that an MCP agent can call directly — no vendor account, no cloud spend, nothing leaving the machine except where a tool's job explicitly requires it.

Reach for something else when you want managed cloud scale instead of self-hosting (a hosted sandbox like E2B or Modal), or when you're not self-hosting at all and the model vendor's built-in code interpreter already covers what you need.

CodeCalc's core opens no sockets. No model gateway or telemetry is built in. tests/test_offline.py asserts this for the top-level core modules. The opt-in Piston provider is the deliberate exception: its wire client lives under codecalc/provider_adapters/ and is registered only when CODECALC_PISTON_URL is configured.

That is a claim about the package, not about every tool call, and the difference is worth stating rather than leaving a reader to discover:

The earlier wording here was an unqualified "it makes no network calls", which the structural test cannot support and three of the tools above contradict. A guarantee stated more broadly than it is enforced is the failure this repo keeps correcting, so it is corrected here too.

The grammar download, stated plainly, because it is the one that is easy to miss. The other three paths above go through a CHILD PROCESS, which is what tests/test_offline.py says it cannot see. This one does not: tree-sitter-language-pack ships a ~5 MB extension and fetches each grammar on first use, in-process, into a local cache — 28 grammars, 89 MB, about 15 seconds on a cold cache. So the first analyze_complexity call for a given language opens a socket from inside the server.

It is verified (the pack checks a signature and raises on a checksum mismatch), it is cached, and it never happens again for that language. But "the package itself never reaches the network" was not true, and this row used to say it was.

For an offline or egress-restricted install, warm the cache first — it is one command, and afterwards nothing here reaches the network. If you installed codecalc (pip install/uvx, not a source checkout), scripts/ did not come with it, so use the shipped console script instead:

codecalc-prefetch-grammars                    # installed: fetch all 28 grammars
codecalc-prefetch-grammars --print-cache-dir  # installed: the directory to copy

Building from source? The script still works and calls the same code:

python scripts/prefetch_grammars.py                    # fetch all 28 grammars
python scripts/prefetch_grammars.py --print-cache-dir  # the directory to copy

codecalc doctor reports whether that cache is populated, so this is discoverable before it matters rather than after a tool call degrades.

codecalc vs. the alternatives

codecalc is not a general cloud sandbox and not a vendor code interpreter. It overlaps with several things and beats them in only one narrow place — forcing a model to measure a claim instead of asserting it. Where that isn't what you need, one of these is the better tool, and this table says so plainly.

Do not reach for codecalc if you need multi-tenant or network-exposed isolation (its threat model is explicitly single-operator, local, stdio), if zero-setup convenience matters more than measurement, or if a hosted interpreter already covers your case. It earns its keep only when the correctness of the claim — not just "it ran" — is the point.

Install

Quickstart with codecalc setup

The fastest path to a working MCP connection, without reading the rest of this section:

uvx 'codecalc[full]' setup            # prints what it would do — nothing on disk changes
uvx 'codecalc[full]' setup --write    # applies it: merges your client's config, copies the skill

It detects which MCP client is installed (Claude Desktop, Claude Code, Cursor, VS Code, Zed — pass --client=NAME if none or several are found), reuses codecalc doctor's own backend/extras/grammar-cache checks, prints the exact config block in that client's own JSON shape with absolute paths already filled in, runs two real canaries (execute_code, evaluate_expression) to prove the connection would work, and ends in one verdict: ready / degraded / not-ready. --write is the only mode that changes anything — it MERGES the codecalc entry into your existing client config (every other server stays exactly as it was) and backs up the original to <path>.codecalc-bak first. codecalc --help lists every subcommand.

[!NOTE] Published as codecalc 0.4.0 on PyPI (pip install codecalc) and the codecalc-exec 0.4.0 executor on crates.io (#91). Every release artifact carries a keyless sigstore build-provenance attestation — verify one with gh attestation verify <file> --repo The-40-Thieves/codecalc; PyPI wheels additionally carry PEP 740 attestations.

From source, if you would rather build the executor yourself:

git clone https://github.com/The-40-Thieves/codecalc
cd codecalc
uv sync --all-extras                 # or: pip install -e '.[full]'
cargo build --release --manifest-path executor/Cargo.toml
mkdir -p bin                         # bin/ is gitignored, so a fresh clone has none
cp executor/target/release/codecalc-exec bin/
uv run codecalc doctor               # verify: backend should read `rust`

Without the cargo build, everything still runs on the pure-Python fallback — doctor will say so, and the network table below says what that costs.

After the first release, this becomes the install:

uvx 'codecalc[full]'          # run it directly, no environment to manage
# or
pip install 'codecalc[full]'  # into your own virtualenv

Why [full]. The base install is the MCP surface and the sandbox executor: 31 language runtimes, sessions, packages, ~32 MB. The symbolic half — sympy and z3 — is 88.6 MB measured, and a caller who only runs code should not download an SMT solver to do it. So it is an extra:

Nothing fails silently: a tool whose extra is missing returns {"ok": false, "error": "sympy is not installed. It ships in the 'symbolic' extra: pip install 'codecalc[symbolic]' ..."}, and codecalc doctor lists which extras are present before you make a call.

.github/workflows/release.yml publishes a platform-tagged wheel per target (Linux x86_64/aarch64 musl, macOS x86_64/aarch64, Windows x86_64), each carrying the matching codecalc-exec binary and — where the platform has one — its --no-net shim, so executor.backend() == "rust" on install without a manual build step. No wheel for your platform, or installed from source instead? Everything still runs; see the network table above for what falls back and to unenforced in that case.

Point an MCP client at the installed command. The key differs by client — mcpServers for most, servers for VS Code, context_servers for Zed — so these are given separately rather than as one snippet to adapt:

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows) · Cursor (.cursor/mcp.json) and Claude Code (.mcp.json) use the same shape:

{ "mcpServers": { "codecalc": { "command": "uvx", "args": ["codecalc[full]"] } } }

VS Code — .vscode/mcp.json, top-level key is servers:

{ "servers": { "codecalc": { "command": "uvx", "args": ["codecalc[full]"] } } }

Zed — ~/.config/zed/settings.json, key is context_servers:

{ "context_servers": { "codecalc": { "command": "uvx", "args": ["codecalc[full]"], "env": {} } } }

Windows paths need doubled backslashes in JSON. If you installed into a venv rather than using uvx, point at the interpreter directly:

{ "mcpServers": { "codecalc": {
    "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
    "args": ["-m", "codecalc"] } } }

Run codecalc doctor to print a config block with the absolute paths of your install already filled in.

Install the skill too. The tools cannot help a model that never reaches for them — a model confident about 0.1 + 0.2 does not feel uncertain, it feels finished. codecalc/SKILL.md ships inside the package and says when calling is mandatory (any non-integer, any comparison you will state, anything past 2^53, any number stated as a claim), when it is noise (2 + 3 + 4 needs no tool), and how results must be reported — passed: true means "equivalent on N inputs", never "verified". codecalc doctor prints its path; copy it into your client's skills directory. check_claims.py gates it, so it cannot name a tool that does not exist or a field no tool returns.

Not sure what your install actually resolved? Ask it, rather than finding out from a tool call later:

codecalc doctor          # or: python -m codecalc doctor

This is the install verification step. It exits 0 when the install can execute — a writable workspace and a resolved backend — and 1 when it cannot, so it works unchanged in a Dockerfile, a provisioning script or a CI job. A missing optional extra or an uninstalled Haskell does not fail it: those are facts about the host, not a broken install, and a check that goes red for them is one people learn to ignore.

It prints the execution backend and the binary behind it, whether installs are confined, the status of every one of the 31 runtimes, whether the workspace is writable, and a client config block with absolute paths filled in. All of that is otherwise discoverable only by making a tool call and reading backend, unenforced, or a failure.

codecalc doctor --json   # the same report, for scripts
codecalc doctor --deep   # actually RUN each runtime, and read its version

--json emits the report and nothing else, against a published schema (docs/contract/doctor-v1.schema.json) carrying the same contract_version and the same policy as a tool result.

Each runtime reports one of four states, and the difference between two of them is which measurement was actually taken:

status_basis says which pass produced them. Without --deep nothing is ever reported available, because nothing was executed, and claiming otherwise for a binary that was merely found on PATH would be a stronger measurement than was taken.

Building the Rust core yourself, or running from a checkout? See "Build the Rust core" and "Run the server" below.

Use it from an MCP client

The shortest version of the config above — this registers codecalc as a stdio MCP server. The console entry point is codecalc, so uvx codecalc launches it directly:

{
  "mcpServers": {
    "codecalc": { "command": "uvx", "args": ["codecalc"] }
  }
}

Installed with pip install codecalc instead? Point at the resolved command with no args:

{
  "mcpServers": {
    "codecalc": { "command": "codecalc" }
  }
}

Architecture (language-per-strength)

Python orchestrates; Rust executes; sympy/z3 reason. Each layer does what it's best at. The Rust binary is preferred automatically; a pure-Python executor is the fallback if the binary is missing.

Older-computer support

• No modern instruction-set requirements — rustc targets a generic CPU by default and nothing overrides it. (executor/.cargo/config.toml explains why -C target-cpu=generic is deliberately NOT written there: it would be a no-op that reads like a guarantee.)
• Static musl builds run on any Linux regardless of glibc version: bin/codecalc-exec-x86_64-musl, bin/codecalc-exec-aarch64-musl (~430K each; the exact size moves with every toolchain bump, so it is not pinned here)
• Size-optimized profile (opt-level="z", LTO, panic=abort, stripped) — measured, not assumed: against an otherwise identical opt-level=3 build, z came out 1.02 ± 0.26 times faster on the executor's own path (i.e. no detectable difference) while being 16% smaller. The executor spends its time in syscalls, not arithmetic, so there was nothing for a higher optimisation level to speed up.
• Lazy sympy/z3 imports. Both are imported on first use, so a session that only executes code never pays for them. This claimed "~40ms, not ~600ms" for a long time while being wrong in both directions: the server took 1.9s to start, and sympy was not actually lazy — units.py imported it at module scope and server.py imports units, so every start paid 437ms for it. Deferring that took spawn-to-first-response from 1888ms to 1243ms (measured, median of 7). The remaining ~870ms is the mcp SDK's own import, which is not ours to remove.
• The fork-bomb measurement is taken once, and only when it is needed. Sizing RLIMIT_NPROC means reading /proc/<pid>/status for every process on the machine. That walk used to run during argument parsing and again for every step: a C compile-and-run opened 1767 status files on a 590-process box to answer one question three times, and --lang notalanguage paid the full cost to produce a one-line error. Measured lazily and cached, an error costs 1.1ms instead of 13.3ms and a compiled run 78ms instead of 104ms.
• list_languages probes runtime availability and reports which languages actually work on the machine (graceful degradation on minimal installs)

Build the Rust core

cd executor
cargo build --release                          # native
cargo zigbuild --release --target x86_64-unknown-linux-musl   # static x86_64 (uses zig)
cargo zigbuild --release --target aarch64-unknown-linux-musl  # static arm64
# Copy the executable AND its --no-net shim together. build.rs rebuilds the
# shim whenever blocknet.c changes, but the executor looks for it beside the
# BINARY, so installing only the binary leaves the previous shim in place — and
# a stale shim silently enforces the old policy while every "is it there?"
# check still passes. Copy both or neither.
mkdir -p ../bin                                # bin/ is gitignored, so a fresh clone has none
cp target/release/codecalc-exec target/release/blocknet.so ../bin/

Requires: Rust 1.97+, a C compiler for the --no-net shim (the build warns and carries on without one; --no-net then reports itself in unenforced rather than pretending), and cargo-zigbuild for the static cross-builds (zig is used as the linker; no x86_64 GCC needed).

MCP tools (52) + MCP resources

Every session file is also exposed as an MCP resource: codecalc://session/<session_id>/files/<path> — images render inline for the model, text returns as text, other files download.

Exact arithmetic & programmer-mode: exact rationals, threshold checks, bit analysis, binary64 introspection.

Core tools

Grade vocabulary

verify_translation, verify_optimization and z3_check return grade + grade_basis (+ grade_rules_version) on top of their own result. The grade names how strong the evidence for a success actually is; it is derived from evidence those tools already emit, in codecalc/grades.py — the verifiers never assign their own grade.

z3_check's sat verdicts are graded ungraded, not solver_proven, even though sat is just as decisive a verdict as unsat. The ticket's motivating pattern is proving a property P by asserting not-P and checking unsat; a caller running that pattern who gets sat back has learned P is FALSE, and solver_proven on that result would let a reader who skims grade without result mistake a counterexample for a proof. sat's grade_basis says so explicitly: satisfiability was decided, but solver_proven is reserved for unsat so a counterexample can never wear a proof grade. Widening sat back into solver_proven later is additive; narrowing it after callers depend on the wider behaviour would not be, so this ships narrow now. Full reasoning: codecalc/grades.py's module docstring.

algebraic_equiv is deliberately NOT graded: it compares two expressions via sympy.simplify(a - b) == 0, a CAS transformation rather than a decision procedure with a checkable certificate, and it is one simplifier's opinion rather than two independent implementations agreeing. None of the three grades describes that evidence honestly.

Runtime self-update

Every language is mapped to its package manager, and codecalc can update its own runtimes:

runtimes_status is always safe. update_runtimes refuses to mutate unless apply=True is passed explicitly — and it only touches the package manager that owns each language (never the Rust sandbox, which has no update powers).

One of those managers is elevated: apt updates system packages, so its command starts with sudo. apply=True is an argument a connected model controls, so that branch takes a second key the model does not have — the host must set CODECALC_ALLOW_RUNTIME_APPLY=1. Without it the apt command is reported as skipped with ok: false and the variable named, while the unprivileged managers still run. sudo -n already fails closed where a password is required; this covers the passwordless-sudo rule common on developer machines and CI images, which is exactly where -n does not stop it.

Run the server

cd /path/to/codecalc && .venv/bin/python -m codecalc.server
# stdio transport — register with any MCP client

# The identical tool/resource registry over stateless Streamable HTTP:
.venv/bin/python -m codecalc.server serve-http --host 127.0.0.1 --port 8000

Streamable HTTP binds to loopback by default and has no CodeCalc authentication layer. Do not bind it to an untrusted network without an authenticating reverse proxy and the stronger process/container isolation described in SECURITY.md.

Point an MCP client at it:

{ "mcpServers": { "codecalc": { "command": "/path/to/codecalc/.venv/bin/python",
                                "args": ["-m", "codecalc.server"],
                                "env": {
                                  "PYTHONPATH": "/path/to/codecalc",
                                  "CODECALC_RUNTIME_PATH": "/path/to/mise/shims:/usr/local/bin:/usr/bin:/bin"
                                } } } }

MCP protocol

Protocol revision 2026-07-28, on the official mcp SDK 2.0. Not fastmcp: fastmcp 3.x pins mcp>=1.24,<2.0 and so cannot reach this revision at all.

Verifying that is less obvious than it looks. mcp.types.LATEST_PROTOCOL_VERSION reads 2026-07-28 regardless of what a given connection negotiated, and the same server answers on either protocol depending only on how you connect:

So tests/test_mcp_protocol.py asserts the negotiated value from a real connection. The legacy path still works — backward compatibility is a feature — it just must not be mistaken for the new protocol.

Worth noting for anyone reading the spec's headline change: 2026-07-28 removes protocol-level sessions, and directs servers needing cross-call state to use "explicit, server-minted handles passed as ordinary tool arguments". That is exactly what codecalc's session_id already is.

The result contract

Every result carries contract_version, currently 1.3.0. The published schema is docs/contract/result-v1.schema.json and the policy behind it — what MAJOR/MINOR/PATCH may change, the twelve-month deprecation window, worked success/failure/timeout examples, and the migration path from unversioned servers — is in docs/contract/README.md.

For in-process Python use, the supported protocol-neutral service boundary—and the session/storage internals that are deliberately not public—is documented in docs/embedding.md.

Two things a caller should know before reading anything else:

• ok means "ran and exited 0". A program that behaves exactly as intended and exits 3 comes back ok: false, exit_code: 3, verdict: "RTE". To tell a failed program from a failed request, read verdict — a request that never reached a runtime has no verdict at all, and has a code instead.
• code is the branch target, not error. Eight stable values; the prose in error is free to improve and is not a contract. An unrecognised code must be treated as internal — that is what lets a 1.x client survive a 2.0.0 server, though adding a code is still a MAJOR change, because the published enum is closed and a strict validator rejects the result first.
• Truncation reports a size, not just a flag. output_truncated says output was cut; stdout_bytes / stderr_bytes say by how much — the bytes the program actually produced, before the cap. A 200 000-character print under max_output_kb=1 returns 1 039 bytes of stdout and stdout_bytes: 200001, so a caller can size a retry instead of guessing. null there means not measured (nothing ran); a program that printed nothing reports 0.

The schema is JSON Schema 2020-12 — the dialect MCP 2026-07-28 defaults tool outputSchema to — so a client can validate our results with it directly. scripts/check_contract.py regenerates it from codecalc/contract.py and fails on a diff, and separately re-derives both backends' verdict vocabularies from main.rs and executor.py: check_parity.py compares the two backends' key sets and is structurally blind to a new verdict value, which would leave the published enum short and make a strictly validating client reject a good result.

Configuration

All optional. codecalc runs with none of these set.

The strict service runs on Linux x86_64 or ARM64 with Docker Engine, cgroup v2, and an explicitly registered gVisor runsc runtime. Its executor image must be pinned by @sha256: digest on the execution path. That image is published to GHCR (ghcr.io/the-40-thieves/codecalc-exec, multi-arch amd64+arm64) by the publish-executor-image workflow, which an operator dispatches (workflow_dispatch); the workflow commits the immutable digest into docker/executor-image.lock, and published_strict_image() resolves it as the production default. Until that first dispatch no digest is pinned and the execution path fails closed — it never falls back to the mutable local diagnostic tag (codecalc-exec:strict), which doctor and the conformance suite keep using. The default systrap platform works without KVM, so the same authenticated service can be used from Linux, macOS, and Windows; strict clients never fall back to native local execution.

Provisioning and running any of the three strict backends in production — the gVisor+Docker host, Windows AppContainer hardening, and the macOS/Windows remote-client configuration — is covered in docs/deployment/README.md, separate from the provider interface itself in docs/contract/provider-v1.md.

Both backends resolve CODECALC_RUNTIME_PATH identically, and scripts/check_parity.py fails CI if the Rust and Python copies of that contract ever drift — including if a machine-specific home directory finds its way back into the default.

Tool-definition token cost

codecalc's tools/list returns 52 definitions. Measured with o200k_base as a proxy, that is roughly 9,200 tokens of descriptions and input schemas, and every client pays it before the first user message.

codecalc does not hide its tools behind a discovery facade, and that is deliberate: the tool surface is where per-operation approval prompts, audit names and typed schemas live, and collapsing 52 tools into one dispatcher makes install_package and percentage look like the same permission to a client that approves by tool name. The cost is real, but the client is the better place to solve it, because the client can defer definitions without giving up the schemas or the per-tool boundary.

If you are paying too much for codecalc's definitions:

• Claude Code enables MCP tool search automatically once a server's tool descriptions exceed roughly 10k tokens. codecalc sits under that threshold, so it is not deferred by default. Set ENABLE_TOOL_SEARCH=true to force it on.
• Claude API, via the MCP connector, takes defer_loading once on the toolset's default_config, or per tool in configs. Deferred definitions stay out of the system-prompt prefix, prompt caching is preserved, and a matching tool is expanded into its full definition when the model searches for it.
• Any client can filter which of the 52 tools it exposes to the model. Nothing here requires codecalc to change.

A server-side facade remains under consideration for clients with no such mechanism (docs/design/2026-08-10-tool-facade.md), and is not implemented.

Reducing the tool surface

For an operator who would rather not configure every client, codecalc also has a first-party knob: CODECALC_TOOLS registers only a chosen slice of the 52-tool surface, so a client that never enables tool search still pays for a smaller tools/list.

This is not the facade the section above declines to build. Every tool a group activates keeps its own name, its own typed input schema and its own per-tool approval prompt — a group that is not active simply never registers its tools with the MCP SDK at all, so they are absent from tools/list and rejected by tools/call, not merely hidden behind a dispatcher a client could still invoke by guessing the name.

Every tool belongs to exactly one group:

CODECALC_TOOLS takes a comma-separated list of group names, preset names, or both:

CODECALC_TOOLS=calculator            # just the calculator (25 tools)
CODECALC_TOOLS=core                  # same thing, by preset name
CODECALC_TOOLS=calculator,execution  # two groups, unioned
CODECALC_TOOLS=dev                   # a coding-assistant slice (39 tools)

Unset or empty registers every group — 52 tools, same as today — so nothing changes for an operator who does not set this. An unknown group or preset name is a loud startup failure naming the bad value and every known group/preset, never a silent fallback to "everything" or "nothing": either direction would turn a typo into a footgun nobody notices until it matters. codecalc doctor prints the active groups, the full group→tools mapping, and how many tools this process actually registered, whatever CODECALC_TOOLS is set to.

Client-side deferred loading (the section above) and this env var compose cleanly: point a client with no deferred-loading mechanism at a CODECALC_TOOLS-restricted process, or use both — a smaller declared surface still benefits from being deferred.

Test

Each file is a standalone script that prints one PASS/FAIL line per assertion and exits non-zero if any failed — no test runner, no plugins.

cd /path/to/codecalc

# everything. `|| break` used to be `|| break` alone, which stopped at the
# first failure AND left the loop exiting 0 — a red suite reported success to
# anything wrapping this command. This form runs them all and carries the
# failure out.
fail=0
for f in tests/test_*.py; do PYTHONPATH=. .venv/bin/python "$f" || { echo "FAILED: $f"; fail=1; }; done
for f in scripts/*.py;    do PYTHONPATH=. .venv/bin/python "$f" || { echo "FAILED: $f"; fail=1; }; done
[ "$fail" -eq 0 ]   # the exit status of the whole run

# or individually
PYTHONPATH=. .venv/bin/python tests/test_smoke.py           # every language, via the Rust executor
PYTHONPATH=. .venv/bin/python tests/test_mcp_all.py         # every tool over MCP stdio, answers checked
PYTHONPATH=. .venv/bin/python tests/test_executor_sweep.py  # sandbox regressions

52 test files and 14 CI-invoked scripts, 2159 assertions. "CI-invoked" means referenced by path (scripts/<name>.py) from a job in .github/workflows/*.yml — scripts/check_claims.py derives the count that way and gates it, so a script wired into a workflow without this sentence changing, or this sentence bumped without a workflow change, fails the build. Nothing in the suite needs the internet, so none of it is ever skipped for lack of a network.

It can skip for lack of a capability, and that is correct rather than a regression: a machine without a symlink privilege, without a given language runtime, or without a built native executor cannot exercise the cases that need them. The suite reports three distinct outcomes — the property holds, the property is broken, and this machine cannot exercise it — and every skip names its real cause. A nonzero skip count on Windows or in fallback mode is the healthy result; what would be wrong is a skip reading as a pass.

This paragraph previously claimed zero skips unconditionally. That became false the moment the suite learned to distinguish the third outcome, and nothing gated it: check_claims.py gates the counts below, not the prose around them. The counts are gated by scripts/check_claims.py: they were written by hand once and were stale within three pull requests, which is exactly the failure the rest of that script exists to prevent. Four of the files are regression suites named after the sweep that produced them — test_bug_sweep, test_executor_sweep, test_python_sweep, test_network_modules — and each one's docstring states the defect it locks out and how it was reproduced, because a regression test whose reason has been forgotten is the first one deleted.

Two rules the suite holds itself to, learned from breaking both:

• Assert the value, not the shape. Three of these files once had no assertions at all: they called tools, printed the output and exited 0. They caught a crash and never a wrong answer — a runtimes_status total replaced with -999 passed, printing total = -999.
• Don't pin what varies. benchmark and compare_execution rank by measured time, so their winner moves under load; their structure is asserted and their timing is not. runtimes_status is checked against itself — the summary must agree with the data it summarises — so it holds on any machine rather than describing this one.

Platform support

Linux, macOS and Windows. The three do not offer the same primitives, and the executor reports which ones it could not apply in an unenforced array on every result rather than letting a caller assume they all held.

The native table below describes the local provider and is not a hostile-code security boundary. On macOS, <host>-strict instead uses the explicitly configured Linux strict service: the macOS binary performs provider selection, attestation, supervision, and result validation, while untrusted code executes inside the remote cgroup/namespace/seccomp/Landlock boundary. A missing or incomplete service fails before source leaves the Mac and never falls back to native execution.

Symbolic evaluation carries the same idea. Every symbolic tool runs SymPy in a forked child under CPU and memory ceilings with a wall clock the parent enforces, so an expression nobody anticipated is still bounded — SymPy's own maintainers abandoned their attempt at a safe= flag as "security theater", so the screen in safe_expr.py buys time and the child buys the bound. Where there is no fork, the result reports expression_bound_not_enforced_without_fork rather than implying a guarantee.

A second field, output_error, covers the other way a result can be wrong: absent means stdout/stderr are what the program produced, present means at least one of them is not, and names which stream and the OS error. That distinction did not exist until #80 — an output file that could not be read came back as a program that printed nothing, on a run reported as successful. ok now accounts for it on both backends.

¹ Darwin accepts setrlimit(RLIMIT_AS) but does not enforce address space the way Linux does, so setting it would buy an illusion. ² Dynamically-linked programs only — a statically linked binary (Go, by default) ignores it. ⁴ Applied via JOB_OBJECT_LIMIT_PROCESS_TIME, which Windows has supported since XP — this was reported as cpu_limit_unavailable_on_windows until 2026-08-08, and the table said the same, so code and docs agreed with each other and disagreed with Windows. It is not identical to RLIMIT_CPU and the difference is reported rather than glossed: it counts user-mode time only, so a process burning kernel time is not capped by it, and the system checks periodically rather than immediately. Runs on Windows carry cpu_limit_counts_user_time_only_on_windows in unenforced to say so.

³ Weaker still on macOS, in two ways. SIP and the hardened runtime strip DYLD_INSERT_LIBRARIES for protected and hardened-signed binaries (most signed interpreters), and dyld interposing does not reach calls made inside the shared cache where libSystem lives — a program's own connect() is intercepted, a system framework opening a connection internally is not. Treat macOS no_net as a speed bump, never as isolation.

Both are exercised by the suite on every platform. The fork-bomb probe measures the EAGAIN boundary precisely but needs os.fork, so it is POSIX-only; a second probe SPAWNS processes instead, which is the portable operation, and pins the ceiling low through CODECALC_MAX_PROCESSES so it costs two dozen short-lived processes rather than walking up to the fallback. Verified to track the limit rather than something incidental: a headroom of 24 bounds it at 22 children and a headroom of 300 bounds it at 298.

⁵ Windows' ActiveProcessLimit is scoped to the job rather than to the uid, so it avoids the failure mode that broke 14 of 31 runtimes on Linux. CodeCalc now supplies that job at process creation, makes it non-nestable with the minimal JOB_OBJECT_UILIMIT_EXITWINDOWS restriction, and allowlists only the three standard I/O handles inherited by the child.

Measured on Windows 11 Pro: 400 of 400 spawns succeeded against a ceiling of 24, reproduced from two unrelated launchers including Task Scheduler. This is not a failed API call — SetInformationJobObject and AssignProcessToJobObject both return success and the correct limit reaches the job. It is topology. ActiveProcessLimit is not one of the limits combined across a nested job chain; those take the most restrictive value, while this one comes from the process's immediate job. A post-creation AssignProcessToJobObject places the child somewhere in that chain rather than at its end: measured, the child's immediate job reported 0x3000 / APL 0 while codecalc's reported 0x230A / APL 24, so codecalc's ceiling was never consulted.

No parent-side Win32 call returns another process's immediate job or its effective ActiveProcessLimit, so this cannot be closed by inspection. Every compatibility run that assigns the child after creation therefore carries process_limit_enforcement_unverified_on_windows in unenforced. Four further strings can each positively prove a failure; none can prove success, so their silence does not imply enforcement.

Creation-time assignment is the default. It was verified on Windows 11 Pro with a direct Python runtime: 23 children succeeded against a total limit of 24 and the next spawn failed with WinError 1816. Runtime launchers that require an inner job now fail rather than silently escaping the limit; configure a direct runtime executable. CODECALC_WIN_JOB_AT_CREATION=0 retains the old path only as an explicitly unverified compatibility escape hatch.

AppContainer security isolation is a DIFFERENT guarantee from the Job Object's resource limits. The Job Object above caps resources — memory, process count, user-mode CPU — and each run names in unenforced which of those did not bind. The optional AppContainer backend adds a security boundary layered on the same creation-time topology: a least-privilege AppContainer profile (CreateAppContainerProfile, no capability SIDs, so no network), launched with SECURITY_CAPABILITIES in the same STARTUPINFOEX attribute list as the job assignment. Access is granted two ways, deliberately split. The sandbox workdir is granted to the run's own AppContainer SID — per-run, so concurrent runs cannot reach each other's workdirs, and it vanishes with the ephemeral directory. The interpreter directory is granted read+execute to the fixed ALL APPLICATION PACKAGES SID (S-1-15-2-1) as an explicit, non-inheritable ACE applied per file across the tree — because a real interpreter's pre-existing files are inheritance-protected and no inheritable grant reaches them. That interpreter grant is persistent and cached (a marker in codecalc's own state dir; the several-thousand-file walk runs once per interpreter): a deliberate trade-off that leaves a read-only ACE, readable by any AppContainer on the machine, on a public interpreter — rather than re-walking every run. The intended property is that a payload cannot read the user profile, write outside its workdir, or reach the network. It is OFF by default (opt in with CODECALC_WIN_APPCONTAINER=1) and fails closed — if profile creation, SID derivation or an ACL grant fails, the launch is refused rather than dropped to an unconfined process. The isolation has been verified on a Windows 11 box (AppContainer SID present, user-profile secrets unreadable, writes confined to the workdir, network denied, ambient privileges reduced to the two benign ones Windows keeps), yet every run that takes this path still emits appcontainer_isolation_unverified_on_windows: a Server-SKU CI runner cannot exhibit AppContainer behaviour, and the guarantee ultimately depends on the deployment's OS and configuration, so the shipped default stays conservatively disclosed rather than claiming a universal proof.

Two things degrade rather than fail on a given platform: languages whose runtime is absent (list_languages reports available: false), and the shell-wrapped plans — gleam and haskell — which need a POSIX shell to scaffold a project and report available: false on Windows outright rather than resolving through a bash that cannot run them. csharp left that set: .NET 10 runs a single .cs file directly, so it is shell-free on every platform.

Reliability tiers

available/status above is a claim about resolution: did this machine find the command on PATH. It is not a claim about reliability: has codecalc's own CI ever actually run this language and checked the output. The two are orthogonal, and they disagree in practice — a review's own smoke test found the rust and csharp host toolchains failing on a machine where both rustc and dotnet resolved cleanly. list_languages, runtimes_status, and codecalc doctor all report a tier alongside resolution to make that gap visible instead of silent:

codecalc doctor's text output prints both axes side by side rather than folding tier into the resolution summary, so a best_effort runtime that happens to be installed on your machine reads as exactly what it is: resolved, unverified by codecalc, may be broken.

Sandbox guarantees

• Fresh temp dir per run, deleted on exit (source + binaries + outputs). The deletion is identity-checked: the directory's device and inode are recorded at creation and re-checked before removal, because executed code runs with that directory as its cwd and can rename another one into its place. A caller-supplied --workdir is a session workspace and is never deleted. If the filesystem supplies no file index to identify the directory by, the deletion is refused rather than performed unverified, so temp directories accumulate there instead of the wrong one being removed. That trade is stated because it is the one this guarantee actually makes: it was previously implemented in the Rust executor only, and the Python fallback deleted unconditionally, which CI caught on Windows.
• rlimits: CPU (timeout+8s), address space 2TiB (V8/JVM need huge VA), file size 256MiB, 256 FDs, core dumps off
• The timeout is a total budget: compile and run share it, so --timeout 10 cannot take twenty seconds. duration_ms is the run alone; compile_ms and total_ms are reported separately.
• Wall-clock timeout kills the whole process group (SIGKILL). So does SIGTERM to the executor — PR_SET_PDEATHSIG reaches only the direct child, so a group kill is what covers its descendants, and the executor is the only participant that knows the group id.
• Output capped at 64KiB per stream, on every path including stateful sessions. Exceeding it is reported as OLE, and the file-size rlimit is kept strictly above the cap so that overflow stays detectable — tying the two together turned a truncated 4MB output into a silent verdict: OK.
• Fork-bomb guard via RLIMIT_NPROC, sized from the measured ambient task count plus headroom rather than a fixed number. This is a mitigation, not isolation: the budget is shared with every other process your user owns, so concurrent executions draw on the same pool. cgroup v2 pids.max is the real per-sandbox answer and needs delegated cgroup access a stdio MCP server cannot assume — reach for it when this moves behind a container.
• no_net blocks the network, not every socket: it refuses AF_INET and AF_INET6 and forwards everything else, so AF_UNIX local IPC keeps working.
• No network namespace isolation (single-host tool; containerize for untrusted code)
• Every result carries a backend field ("rust" or "python") so a caller never has to infer which sandbox actually ran from an absent key — that was possible to confuse with an older build that never reported it at all. The pure-Python fallback cannot provide everything above: it has no no_net shim (reported in unenforced, not silently dropped), and peak_memory_kb comes back None rather than a number, because ru_maxrss is a process-lifetime high-water mark this path has no way to attribute to one run. CODECALC_REQUIRE_NATIVE=1 turns "running on the fallback" into a startup failure instead of a guarantee you have to notice was quietly weaker.

Sessions

A session is a persistent workspace; python3 and node additionally get a long-lived REPL worker so variables and imports survive between calls. What that does and does not buy you:

A worker cannot take a per-call rlimit after the fact, and --no-net is decided at exec time. Rather than accept those arguments and drop them, the result lists them in unenforced — the same field the executor already uses to say "asked for, not applied". Omit session_id, or use a workspace session, when a ceiling has to be real.

The worker protocol does not share a file descriptor with executed code, and every response carries the id of the request it answers. Both matter: sys.stdout is a Python-level rebind that a subprocess writes straight past, and a corrupted stream that is not resynchronised returns every later call the previous call's result — a well-formed answer to a different question.

The channel differs by platform and the guarantee does not. POSIX hands the worker an out-of-band pipe; Windows has neither pass_fds nor preexec_fn, so the worker appends responses to a file whose path arrives in the environment. Either way a child spawned with inherited stdio writes to fd 1 and cannot reach the protocol. Tests force the file-backed channel on every platform, because an unexercised fallback is one that works until it is needed.

Local operations: status & cleanup

Two CLI-only commands for an operator running a long-lived server, not MCP tools — they don't count toward the tool surface above:

codecalc status          # read-only snapshot: sessions, disk usage, quotas, audit log
codecalc status --json   # the same report, for scripts

codecalc cleanup                          # DRY RUN (the default) — marker-based only
codecalc cleanup --write                  # actually removes marker-based candidates
codecalc cleanup --write --include-unmarked   # ALSO sweep old, unmarked, session-shaped dirs

status reports SESSION_ROOT, how many sessions exist and which of them are idle-expired (the on-disk .codecalc-session-expired marker THE-894's idle-TTL reaping leaves behind), per-session and global workspace disk usage, the configured disk quotas and current headroom, the audit log's path and size, and a one-line runtime reliability-tier summary. It changes nothing — no session is started, stopped, reaped, or written to.

cleanup reclaims disk from session directories under SESSION_ROOT. --dry-run is the default — nothing is removed until --write is passed. Because cleanup runs as a SEPARATE process from any server that may be using SESSION_ROOT right now, it has none of that server's in-memory bookkeeping to consult — only what is on disk.

Directory mtime is deliberately NOT trusted as a liveness signal. An earlier version of this feature did trust it, and an adversarial review proved that wrong live: a REPL worker doing purely in-memory work touches no file at all, and even an in-place file overwrite bumps only that file's own mtime, never its parent directory's — so a genuinely-active worker session can look, by directory mtime alone, identical to an abandoned one. The real signal is a per-worker-session liveness lockfile: the server writes its own pid into the session directory the moment a stateful (python3/node) worker starts, and removes it the moment that worker is actually gone (reaped or session_stop). cleanup checks this for every candidate and refuses outright — regardless of marker, age, or the mtime floor below — whenever the lockfile names a pid that is still alive. That is what makes a session any running codecalc server is using is never deleted true for worker sessions.

By default, cleanup considers ONLY directories carrying the idle-expiry marker — the risk-free path, since a marker only ever exists after sessions.py's own idle-TTL reaper has already closed that specific worker for good (session ids are never reused). --include-unmarked additionally sweeps old (CODECALC_CLEANUP_ABANDONED_AGE_HOURS, default 24h), session-shaped, marker-less directories — the one path with real residual risk, because a workspace-only session (no worker) never gets a lockfile to check against, so this path falls back to age + a hard recency floor (nothing modified in the last few minutes is ever touched) as a heuristic, not a proof. Turn it on deliberately, and never point CODECALC_SESSION_ROOT at anything but a codecalc-private directory — the "looks like a session dir" name filter is loose, not strict.

Other safety properties, unconditional on every path: only a direct child of SESSION_ROOT is ever a candidate (never SESSION_ROOT itself); a symlink there is refused, never followed; and removal itself is identity-checked (device/inode, re-verified immediately before the delete) the same way session_stop's own workspace teardown is, so a directory swapped out from under a stale scan is refused rather than deleted.

Language list

python3, node, bun, deno, typescript, ruby, php, perl, lua, tcl, r, elixir, erlang, bash, zsh, mojo, swift, c, cpp/c++, rust, go, fortran, zig, java, kotlin, csharp, gleam, haskell, sqlite, jq, awk — 31 runtimes.

codecalc does not install any of them. It runs whatever is already on CODECALC_RUNTIME_PATH, and list_languages probes each one and reports which actually resolved, so a minimal machine degrades to the subset it has rather than failing opaquely.

Notes

• Java uses single-file source launch (JEP 330). Kotlin compiles to a jar.
• gleam/haskell scaffold a temp project (gleam new / nix-shell); csharp runs the file directly (.NET 10 file-based apps).
• benchmark uses the stdin-N contract: code reads N from stdin, work sized by N.

CI

Five workflows, each documented inline with what it gates and — where a tool was considered and rejected — why it is not there.

Two conventions run through all of them, both borrowed from harder-won experience:

• Actions are pinned by commit SHA and downloaded tools by SHA-256. A tag is mutable; a digest is not.
• Every scan asserts it scanned something. A linter pointed at a renamed directory, a dependency scanner with no lockfile to read, and a clean repo all produce the same output — exit 0. Each gate counts its inputs first and fails if the count is implausible.

Licence

Apache-2.0. See LICENSE.

Contributions require a DCO sign-off (git commit -s); dco.yml enforces it.