quartermaster-code-runner

Secure sandboxed code execution service. Runs untrusted code in isolated Docker containers with support for Python, Node.js, Go, Rust, Deno, and Bun.

Features

• 6 Runtimes: Python, Node.js, Go, Rust, Deno, Bun
• Docker Isolation: Each execution runs in its own container with read-only filesystem
• Resource Limits: Configurable CPU, memory, and disk quotas per execution
• Network Control: Outbound network access toggled per request
• Timeout Enforcement: Hard container kill after configurable duration
• File Injection: Send multiple source files alongside the main code
• Prebuilt Images: Extend base runtimes with custom dependencies
• Auto Cleanup: Orphaned containers and old images cleaned up automatically
• API Key Auth: Optional authentication via X-API-Key header or Bearer token
• Health Checks: Built-in /health endpoint with Docker connectivity status
• Standalone: No dependency on other Quartermaster packages

Supported Runtimes

Installation

As a Service (recommended)

pip install quartermaster-code-runner
uvicorn quartermaster_code_runner.app:app --host 0.0.0.0 --port 8000

Requires Docker to be running and accessible.

Docker Compose

services:
  code-runner:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - LOG_LEVEL=info
      - DEFAULT_TIMEOUT=30
      - DEFAULT_MEMORY=256m

Quick Start

Execute Python Code

curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(sum(range(1, 101)))",
    "image": "python"
  }'

Response:

{
  "stdout": "5050\n",
  "stderr": "",
  "exit_code": 0,
  "execution_time": 0.3421
}

Execute Node.js Code

curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "console.log(Array.from({length: 5}, (_, i) => i * i))",
    "image": "node"
  }'

With Environment Variables and Resource Limits

curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import os; print(os.environ[\"API_KEY\"])",
    "image": "python",
    "timeout": 10,
    "mem_limit": "128m",
    "cpu_shares": 256,
    "allow_network": false,
    "environment": {
      "API_KEY": "secret-123"
    }
  }'

With Additional Files

curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "from helpers import greet; print(greet(\"world\"))",
    "image": "python",
    "files": {
      "helpers.py": "def greet(name): return f\"Hello, {name}!\""
    }
  }'

Python Client Usage

from quartermaster_code_runner import CodeExecutionRequest

request = CodeExecutionRequest(
    code="print('Hello from the sandbox')",
    image="python",
    timeout=10,
    mem_limit="128m",
    allow_network=False,
)

API Reference

POST /run

Execute code in a sandboxed Docker container.

Request body (CodeExecutionRequest):

Response (CodeExecutionResponse):

GET /health

Returns service health and Docker connectivity.

{
  "status": "ok",
  "docker_connected": true,
  "auth_enabled": false
}

GET /runtimes

List available runtime images with metadata (alias for /images).

{
  "images": [
    {
      "id": "code-runner-python",
      "name": "Python",
      "description": "Python runtime",
      "default_entrypoint": "python main.py",
      "file_extension": ".py",
      "main_file": "main.py"
    }
  ],
  "default": "code-runner-python"
}

POST /prebuild

Build a prebuilt image extending a base runtime with custom dependencies.

curl -X POST http://localhost:8000/prebuild \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "my-scipy",
    "base_image": "python",
    "setup_script": "pip install scipy numpy"
  }'

GET /prebuilds

List all prebuilt images. DELETE /prebuilds/{tag} removes one.

Security Model

Each execution is isolated with multiple layers:

1. Container isolation -- separate Docker container per execution
2. Read-only filesystem -- containers run with read_only=True; writes go to tmpfs
3. Network control -- outbound access disabled when allow_network=false
4. Resource limits -- CPU shares, memory limit, disk quota enforced by Docker
5. Timeout enforcement -- containers killed after the configured timeout
6. Input validation -- code size capped at 1 MB; reserved env vars blocked; path traversal rejected

Reserved environment variables (ENCODED_CODE, ENCODED_FILES, CUSTOM_ENTRYPOINT) cannot be overridden by callers.

Configuration

All settings load from environment variables with sensible defaults. Use a .env file or set them directly.

Environment Variables

When neither AUTH_TOKEN nor CODE_RUNNER_API_KEYS is set, authentication is disabled.

Error Types

from quartermaster_code_runner import (
    CodeRunnerError,  # Base exception
    DockerError,  # Docker communication failure
    ExecutionError,  # Code execution failure
    InvalidLanguageError,  # Unsupported runtime
    ResourceExhaustedError,  # Resource limit exceeded
    RuntimeNotAvailableError,  # Runtime image not found
    TimeoutError,  # Execution timeout
)

Contributing

Contributions welcome. See CONTRIBUTING.md for guidelines.

License

Apache License 2.0. See LICENSE for details.