code-runner

An open-source, self-hostable remote code execution service with live interactive stdin.
Run untrusted code in a hardened sandbox and stream output in real time over soketi (Pusher-compatible).

Quickstart · Architecture · API · SDKs · Add a language · Deploy

What it is

code-runner is a Piston-style remote execution service, built as a polyglot monorepo, that does one thing well: take some code, run it in an isolated hardened sandbox with a live interactive stdin session, and stream the output back in real time — without ever leaking a container, a subscription, or a session slot.

It is an internal service: never exposed to the internet directly. In front of it sits your own backend (any stack), which authenticates with a bearer token. Browsers only ever receive output — over soketi — and never send trusted input directly.

Architecture

All trusted input (code, stdin, control) enters through one bearer-authed door — the API. soketi is output-only toward the client; nothing trusted ever enters through it.

The components

• apps/api — Hono / TypeScript. The single trusted entry point. Validates requests (constant-time bearer auth), resolves the language manifest, writes the job to Redis, and relays stdin & control signals. Stateless → runs anywhere, scales to N replicas.
• apps/worker — Go. Claims jobs from Redis, launches hardened sandboxes via the host Docker daemon (behind a swappable Runner interface), enforces the three clocks, pumps stdin in and streams output out. The unit of scale.
• Density tier (optional). A ZygoteRunner can run heavy interpreted languages (Python) on a warm copy-on-write pool for ~2.7× concurrency on Fly — off by default, falls back to per-job containers. See docs/zygote.md.
• packages/contract — JSON Schema → TS + Zod + Go. The shared wire contract. One schema generates types for every language; a CI drift check guards the seam.
• Redis — job queue (jobs:queue), stdin/control pub-sub (stdin:<id>, ctrl:<id>), and job metadata (job:<id>:{spec,status,output}).
• soketi — Pusher-compatible WebSocket fan-out. The worker triggers; soketi delivers to subscribers.

Quickstart

Prerequisites

• Docker Desktop running (cgroup v2 required for resource limits)
• Node.js 22+ and pnpm 10+ · Go 1.26+
• Ports 8080 (API) and 6001 (soketi) free

Five steps to a working interactive run

# 1. Copy env (all defaults are safe for local dev)
cp .env.example .env

# 2. Build the language sandbox images on the host daemon (no Docker-in-Docker)
make build-images       # executor/python:3.12  rust:1.83  c:14  cpp:14  r:4.4  sqlite:3

# 3. Bring up the stack: redis + soketi + api + worker
docker compose up       # or: make up

# 4. Run the interactive end-to-end demo
make e2e

# 5. Tear down
make down

make e2e drives an interactive Python program that prompts for a name, sends World over stdin, and asserts the round-trip:

[stub] stdout: name?
[stub] detected prompt, sending stdin: World
[stub] stdout: hello World
[stub] result: exitCode=0 reason=exit durationMs=...
[PASS] ===== E2E PASS: interactive execute hello World round-trip succeeded =====

Health check (no auth): curl http://localhost:8080/health → {"status":"ok"}.

Interactive flow

The start-handshake is the crux: the worker parks the job until you signal start, so your client is guaranteed to be subscribed before any output is emitted (soketi pub-sub drops events that have no live subscriber).

The three clocks

Each sandbox is bounded by three independent clocks; any one firing kills it:

Plus memoryMb (OOM kill, swap disabled), pids (fork-bomb guard), and outputKb (combined stdout+stderr budget; overflow → truncated).

API Reference

All /v1/* endpoints require Authorization: Bearer <EXECUTOR_API_TOKEN>. A missing or invalid token → 401 {"error":"unauthorized"} (constant-time comparison). GET /health is the only unauthenticated route.

// Request body
{
  "language": "python",            // name or alias: "py", "rust", "rs", "c", "cpp", "c++", "sqlite", "sql", …
  "version": "3.12",               // optional; omit to use the only/most-recent match
  "files": [
    { "name": "main.py", "content": "name = input('name? ')\nprint(f'hello {name}')\n" },
    { "name": "data/input.csv", "content": "a,b\n1,2\n" },           // subdir: written to /workspace/data/input.csv
    { "name": "fixtures/sheet.xlsx", "content": "UEsDBBQ…", "encoding": "base64" } // binary file
  ],
  "limits": {                      // optional per-request overrides; absent → manifest defaults
    "wallTimeMs": 30000, "idleMs": 10000, "cpuMs": 15000,
    "memoryMb": 128, "pids": 64, "outputKb": 512
  },
  "collectOutput": false           // true → persist a pullable RunResult
}

{ "jobId":"<uuid>", "channel":"private-run-<uuid>", "language":"python",
  "version":"3.12", "state":"running", "updatedAtMs":1700000000000 }

{ "exitCode":0, "signal":null, "timedOut":false, "idleTimedOut":false,
  "truncated":false, "durationMs":312, "stdout":"hello World\n", "stderr":"",
  "artifacts":[{ "name":"plot.png", "mimeType":"image/png", "bytes":20481, "url":"https://…" }],
  "artifactsTruncated":false }

[ { "language":"python", "version":"3.12", "aliases":["py","py3","python3"], "interactive":true } ]

Client SDKs

Three published packages cover both sides of the trust boundary:

Backend (submit + drive):

import { CodeRunnerClient } from "@teovilla/code-runner-sdk-node";

const client = new CodeRunnerClient({ baseUrl: "http://localhost:8080", token: process.env.EXECUTOR_API_TOKEN! });
const job = await client.execute({ language: "python", files: [{ name: "main.py", content: "print(input())" }] });
// subscribe on the browser, then:
await client.start(job.jobId);
await client.sendStdin(job.jobId, "world\n");

Binary + subdir inputs — pass a Buffer and the SDK base64-encodes it for you (encoding:"base64"):

import { readFileSync } from "node:fs";

await client.executeFiles({
  language: "python",
  files: [
    { name: "main.py", content: "import openpyxl; print(openpyxl.load_workbook('data/sheet.xlsx').active.max_row)" },
    { name: "data/sheet.xlsx", data: readFileSync("./sheet.xlsx") }, // binary → base64 transparently
  ],
});

Browser (subscribe to live output):

const { stage, stdout, stderr, result, sendStdin } = useCodeRunnerJob({
  jobId,
  onStdin: (chunk) => fetch(`/api/jobs/${jobId}/stdin`, { method: "POST", body: JSON.stringify({ chunk }) }),
});

The bearer token and soketi APP_SECRET never leave the server — the browser receives output only and routes actions back through your backend. See each package's README for the full API.

Adding a language

Languages are self-contained packages in languages/<lang>-<version>/. Adding one needs zero changes to the worker or the API — only a folder, a manifest.json, and a Dockerfile. A language is defined entirely by image + compile? + run.

// languages/rust-1.83/manifest.json  (a compiled language)
{
  "language": "rust", "version": "1.83", "aliases": ["rs"],
  "image": "executor/rust:1.83", "entrypoint": "main.rs",
  "compile": ["rustc", "-O", "main.rs", "-o", "/workspace/prog"],   // null for interpreted langs
  "run": ["/workspace/prog"],
  "interactive": true,
  "defaultLimits": { "wallTimeMs": 120000, "idleMs": 15000, "cpuMs": 60000, "memoryMb": 512, "pids": 128, "outputKb": 1024 }
}

make rust-image          # build executor/rust:1.83 on the host daemon (or: make build-images)
docker compose up --build  # the manifest loader auto-discovers the new folder at boot
curl localhost:8080/v1/languages -H "Authorization: Bearer $EXECUTOR_API_TOKEN"  # verify

Bundled languages: Python 3.12, Rust 1.83, C and C++ (GCC 14), R 4.4, SQLite 3 — the last two prove the abstraction holds for a non-interactive language and a non-general-purpose tool.

Deployment

Scaling unit: the worker node. A long-lived Go process that claims jobs and launches sandboxes internally (up to WORKER_MAX_SANDBOXES). Autoscale the fleet by LLEN jobs:queue.

• Fly.io — fly-autoscaler on the Redis llen metric; a four-app reference deploy lives in deploy/fly and is documented in docs/deploy-fly.md.
• Kubernetes — KEDA's Redis scaler on LLEN jobs:queue, or an HPA custom metric.
• Extra isolation — set SANDBOX_RUNTIME=runsc to run under gVisor with no code changes; the Sentry intercepts all syscalls.

The API is stateless (runs anywhere, serverless OK). soketi runs as a sidecar or standalone. See docs/scaling.md for the full topology and scale-to-zero caveats.

Observability (bring-your-own OpenTelemetry)

Both API and worker are fully OpenTelemetry-instrumented but ship telemetry-off by default — zero overhead until you set OTEL_EXPORTER_OTLP_ENDPOINT. When enabled, one execution produces a single connected trace spanning the API and the worker (claim → sandbox.create → handshake.wait → compile → run → publish.result). An example collector + Jaeger ships inert under the observability compose profile:

docker compose --profile observability up --build
bash scripts/observability-e2e.sh    # → Jaeger UI: http://localhost:16686

Safety gate

The adversarial abuse suite (internal/worker/abuse_test.go, build tag abuse) is the required gate before any language is added. It drives 7 hostile jobs through the full worker path on real Linux cgroup v2 — OOM kills, CPU throttling, wall-time expiry, idle timeout, PID exhaustion, output truncation, and clean-exit containment.

make python-image
docker run -d -p 6381:6379 redis:7
make abuse

CI (.github/workflows/abuse.yml) runs it on every PR on ubuntu-latest. Repo owners should make "abuse / abuse" a required status check on main so fan-out PRs can't merge unless it's green.

Make targets

Repository layout

apps/
  api/        Hono/TypeScript gateway          packages/
  worker/     Go worker + sandbox runner         contract/              wire contract (schema → TS+Zod+Go)
  stub/       interactive E2E driver             code-runner-sdk-node/  server SDK
  docs/       Fumadocs documentation site        code-runner-react/     browser SDK
internal/     Go packages (runner, session,    languages/    one folder per language (manifest + Dockerfile)
              jobstore, publisher, reaper, …)  profiles/     seccomp profile
deploy/fly/   Fly.io reference deploy          observability/ OTel collector config

Contributing

Contributions are welcome. The one hard rule before merging a new language or a worker change: the abuse suite must be green. See Safety gate. Run make test and make contract-check before opening a PR.

License

MIT — self-hostable, no strings attached.