code_execution_runtime

A service exposing an endpoint that runs a bash command inside a namespace-scoped sandbox with a persistent filesystem.

• Design & trade-offs: see ARCHITECTURE.md.
• This repo runs the local development backend end to end. The production backend (Firecracker microVM + EBS, with Redis ordering and a DynamoDB registry) is documented and stubbed behind the same traits, and declared as Terraform under terraform/.

Requirements

• Linux. The local sandbox uses cgroups v2, Landlock, and Unix process APIs.
• A recent stable Rust (edition 2024; developed against 1.93).
• bash on PATH.

Run

cargo run
# listening on http://0.0.0.0:8080

Configuration (all optional; a .env file is loaded if present — see .env.example):

Variable	Default	Purpose
PORT	8080	Port to listen on.
SANDBOX_FS_ROOT	./namespaces	Where each namespace's directory lives (the local stand-in for its attached volume).
RUST_ENV	local	local selects the in-memory + child-process backends. Anything else selects the production backends (placeholders — not runnable here).

# put namespace directories somewhere else
SANDBOX_FS_ROOT=/tmp/ns cargo run

Endpoints

• POST /execute — body {"namespace_id": "...", "cmd": "..."}, returns {"stdout": "...", "stderr": "...", "exit_code": <int|null>}. exit_code is null if the process was killed by a signal. A command that exits non-zero is not an error — you get 200 OK with its output and exit code. Other statuses: 400 invalid namespace_id, 503 namespace busy / provisioning failed (retry), 500 internal error.
• GET /health — 200 OK, used by the load balancer health check.

Use

# write a file in namespace "alice"
curl -s localhost:8080/execute \
  -H 'content-type: application/json' \
  -d '{"namespace_id":"alice","cmd":"echo hello > note.txt && cat note.txt"}'
# {"stdout":"hello\n","stderr":"","exit_code":0}

# the file persists across requests in the same namespace
curl -s localhost:8080/execute \
  -H 'content-type: application/json' \
  -d '{"namespace_id":"alice","cmd":"cat note.txt"}'
# {"stdout":"hello\n","stderr":"","exit_code":0}

# a different namespace has its own filesystem and cannot see it
curl -s localhost:8080/execute \
  -H 'content-type: application/json' \
  -d '{"namespace_id":"bob","cmd":"cat note.txt"}'
# {"stdout":"","stderr":"cat: note.txt: No such file or directory\n","exit_code":1}

Test

cargo test

Unit tests cover the per-namespace ordering guarantee (src/coordinator/in_memory.rs). Integration tests in tests/local_flow.rs drive the full local stack (HTTP → ordering → provisioning → real bash): persistence within a namespace, isolation between namespaces, stdout/stderr/exit-code plumbing, namespace_id validation, and the health check.

Layout

Path	Responsibility
src/lib.rs	Wiring: builds the router for the local or production backends.
src/main.rs	Binary entry point: serve the router over HTTP.
src/api.rs	HTTP transport: /execute, /health, namespace_id validation.
src/executor.rs	Per-namespace in-order execution (order → run → release).
src/coordinator/	FIFO ordering + lock: InMemoryCoordinator (local), RedisCoordinator (prod).
src/provisioner.rs	Make a namespace's volume/VM ready: MockProvisioner (local), AwsProvisioner (prod placeholder).
src/sandbox/	The execution backend boundary: local (child process), remote + firecracker (prod placeholders), limits (cgroups/Landlock).