Jet ⚡

Jet is a high-performance, resilient, and multi-tenant sandboxed remote code execution engine and online judge platform written in Rust.

Engineered to evaluate untrusted code securely and at scale, Jet combines Linux kernel-level container isolation (via Hakoniwa, Linux namespaces, and cgroups v2) with an asynchronous task queue, Multi-Level Parallelism (MLP) for compile vs. execute scheduling, HMAC-authenticated rate limiting, dynamic toolchain package management, and real-time observability.

Key Features

Kernel-Level Sandboxing: Enforces strict isolation with Linux namespaces (Mount, Pid, Cgroup, Ipc, Network, Uts), tmpfs mounts, read-only system paths, and cgroups v2 memory, CPU, and PID limits.
Multi-Level Parallelism (MLP): Dispatches heavy compilation jobs and lightweight runtime execution jobs through dedicated semaphores and concurrency limits, preventing compile spikes from starving evaluation queues.
Comprehensive Failure Detection: Accurately traps and reports:
- TIME_LIMIT_EXCEEDED (TLE) — wall-clock and CPU time limits.
- MEMORY_LIMIT_EXCEEDED (MLE) — cgroup physical memory caps.
- OUTPUT_LIMIT_EXCEEDED (OLE) — stream byte truncation protection.
- FORK_BOMB Protection — strict PID limits preventing process table exhaustion.
- COMPILATION_ERROR & RUNTIME_ERROR — granular stdout/stderr capture and exit code reporting.
Dynamic Toolchain Package Manager (jet-pack): Automated downloading, tarball extraction, SHA256 integrity verification, and version aliasing for multiple languages (e.g. python:3.14, java:21, zig:latest).
Resilient Queue & Worker Architecture: Backed by Redis (apalis-redis + deadpool-redis) with queue-time shedding (dropping stale jobs over max_queue_wait_secs) and backpressure thresholds.
Enterprise Traffic Defense:
- HMAC-SHA256 request signature verification with replay protection via Redis nonce tracking and timestamp drift limits.
- Multi-tier token-bucket rate limiting via tower_governor across submit (per-user), poll (per-user), and public/general endpoints.
Real-Time Admin Operations: Live administrative endpoints to tune queue depth thresholds dynamically and preempt in-flight execution via graceful interrupts.
Production CLI (jet-cli): Interactive execution, live progress bars, automated local environment bootstrap, concurrent load benchmarking, and systemd unit file generation.

Architecture

flowchart TD
    Client["Client / CLI / Webhook"]
    
    subgraph JetServer["Jet Server (Axum)"]
        AuthMiddleware["HMAC-SHA256 & Nonce Check"]
        RateLimiter["Token-Bucket Rate Limiter (tower_governor)"]
        Router["HTTP Router (/jobs, /runtimes, /stats, /admin)"]
        Resolver["Version Resolver & Manifest Cache"]
        QueueClient["Queue Producer (apalis-redis)"]
    end

    subgraph Storage["Redis"]
        JobQueue[("Job Queue (apalis)")]
        JobStates[("Job State Cache (jet:jobs:*)")]
        NonceStore[("Nonce Replay Keys (jet:auth:nonce:*)")]
        VersionStore[("Version Manifests (jet:version_map)")]
    end

    subgraph WorkerPool["Worker Pool (Supervisor & Hakoniwa)"]
        WorkerRunner["Worker Runner (apalis Consumer)"]
        MLP["MLP Semaphores (Compile vs Execute)"]
        Supervisor["Process Supervisor (--jet-child-eval)"]
        
        subgraph Sandbox["Hakoniwa Isolated Container"]
            Namespaces["Namespaces: Mount, PID, Net, IPC, UTS, Cgroup"]
            Cgroups["Cgroups v2: Memory Limits, PID Limits"]
            Mounts["Mounts: RO /bin, /usr, /lib | Ephemeral /tmp, /workspace"]
            CodeExec["Code Execution / Compiler"]
        end
    end

    Client -->|HTTP Request with HMAC| AuthMiddleware
    AuthMiddleware --> RateLimiter
    RateLimiter --> Router
    Router --> Resolver
    Router --> QueueClient
    QueueClient --> JobQueue
    
    WorkerRunner -->|Pulls Job| JobQueue
    WorkerRunner --> MLP
    MLP --> Supervisor
    Supervisor -->|Fork Child Process| Sandbox
    Sandbox --> Mounts
    Sandbox --> CodeExec
    
    CodeExec -->|StageResult: CPU, Mem, Stdout/Stderr| Supervisor
    Supervisor -->|Save Result| JobStates
    Router -->|Poll Status| JobStates

Workspace Crates & Apps

Crate / App	Type	Description
`apps/jet-server`	Application	Asynchronous Axum web service, Redis job queue, rate limiting, and Hakoniwa worker supervisor.
`apps/jet-cli`	Application	Command-line interface for running jobs, load-testing benchmarks, runtime installation, and server control.
`crates/jet-core`	Library	Core domain models (`JobRequest`, `JobResult`, `StageStatus`), limit definitions, configuration parsing, and error types.
`crates/jet-pack`	Library	Runtime package manager, archive unpacker (tar, gz, xz, zip), version resolver, and manifest generator.
`vendor/libcgroups`	Vendored	Patched cgroups v2 controller bindings used for resource accounting and limits.

Supported Runtimes & Languages

Jet supports both compiled and interpreted languages with pre-configured manifests and starter templates:

Language	Model	Default Compiler / Interpreter	Supported Features
Python	Interpreted	Python Standalone (`python`)	Custom arguments, STDIN, multi-file execution
C	Compiled	GCC / Clang (`gcc -O2`)	Multi-file programs, math libraries, strict rlimits
C++	Compiled	G++ / Clang++ (`g++ -O2 -std=c++20`)	STL algorithms, template compilation, strict rlimits
Rust	Compiled	`rustc -O`	Memory bounds, borrow-checker compile errors
Java	Compiled + JVM	Amazon Corretto (`javac` + `java`)	Custom JVM heap flags, multi-class execution
Zig	Compiled	`zig build-exe`	Fast compilation with dedicated `/opt/zig-cache`

Security & Sandboxing Model

Jet provides multi-layered defence-in-depth against malicious code and resource exhaustion:

Namespace Isolation:
- Namespace::Mount: Clean mount namespace with root filesystem mounted read-only (/bin, /lib, /usr, /lib64).
- Namespace::Network: Network namespace completely disabled (unshare(Network)). Sandboxed code cannot access internal network interfaces or the public Internet.
- Namespace::Pid: Code executes in an isolated PID namespace where it cannot see or signal host processes.
- Namespace::Ipc & Namespace::Uts: Dedicated IPC and UTS namespaces preventing shared memory or hostname spoofing.
Cgroups v2 Resource Accounting:
- Memory: Strict physical memory enforcement (memory.max). Exceeding memory triggers MEMORY_LIMIT_EXCEEDED without host OOM kills.
- PIDs: Tight process count limits (pids.max), instantly neutralizing fork bombs.
Storage & Ephemeral Workspaces:
- /tmp is mounted as an independent in-memory tmpfs.
- /workspace is isolated per job execution and wiped immediately upon completion.
- Job IDs and paths are strictly validated to prevent path traversal attacks.
Supervisor Isolation:
- Evaluations run in separate child supervisor processes (--jet-child-eval). If a sandbox freezes or hits wall-clock timeouts, the parent supervisor forces termination via hard process termination.

Prerequisites

Linux (Kernel 5.8+ recommended, cgroups v2 enabled and mounted at /sys/fs/cgroup).
Rust Toolchain: Rust 1.85+ (2024 edition).
Redis: 6.2+ (standalone or cluster) for queue storage and state caching.
Build Tools: gcc, tar, xz, unzip, pkg-config, libssl-dev.

Installation & Building

Clone the repository and build in release mode:

git clone https://github.com/Harshith-10/jet.git
cd jet

# Build all workspace packages
cargo build --release

Binaries will be available in target/release/:

target/release/jet-server
target/release/jet-cli

Configuration

Jet can be configured via environment variables or a TOML configuration file specified with JET_CONFIG_PATH.

Environment Variables

Variable	Default	Description
`JET_CONFIG_PATH`	None	Optional path to a `jet.toml` configuration file.
`JET_SERVER_HOST`	`0.0.0.0`	Host address to bind the API server.
`JET_SERVER_PORT`	`4000`	Port to bind the API server.
`JET_REDIS_URL`	`redis://127.0.0.1:6379`	Redis connection URL.
`JET_RUNTIME_DIR`	`~/.jet/runtimes`	Root directory for installed runtimes and workspaces.
`JET_RUNTIME_MANIFEST_DIR`	`<JET_RUNTIME_DIR>/manifests`	Directory containing language manifest YAML files.
`JET_RUNTIME_CACHE_KEY`	`jet:version_map`	Redis key storing resolved runtime versions.
`JET_WORKER_CONCURRENCY`	`CPU cores`	Total number of concurrent worker tasks.
`JET_COMPILE_CONCURRENCY`	`max(1, cores / 4)`	Concurrency limit for compilation stages.
`JET_EXECUTE_CONCURRENCY`	`cores - compile`	Concurrency limit for execution stages.
`JET_MAX_QUEUE_DEPTH`	`concurrency * 10`	Max queued submissions before rejecting with HTTP 429/503.
`JET_MAX_QUEUE_WAIT_SECS`	`30`	Max duration a job can wait in queue before queue-shedding.
`JET_RATE_LIMIT_HMAC_KEY_ID`	Required	Secret key identifier for HMAC verification.
`JET_RATE_LIMIT_HMAC_SECRET`	Required	Shared secret string for HMAC-SHA256 signature verification.
`JET_ADMIN_ALLOWED_USER_IDS`	Required	Comma-separated user IDs authorized for `/admin/*` operations.
`JET_RATE_LIMIT_TIMESTAMP_TOLERANCE_SECS`	`300`	Max clock drift allowed for request timestamps.
`JET_RATE_LIMIT_NONCE_TTL_SECS`	`300`	Redis expiration time for nonce replay protection.

Example `jet.toml`

server_host = "0.0.0.0"
server_port = 4000
redis_url = "redis://127.0.0.1:6379"
runtime_install_dir = "/var/lib/jet/runtimes"
runtimes_manifest_dir = "/var/lib/jet/runtimes/manifests"
runtime_cache_key = "jet:version_map"

Running Jet

1. Start Redis

redis-server --daemonize yes

2. Manage Runtimes with `jet-cli`

Before starting the server, install desired language runtimes using jet-cli:

# List available and installed runtimes
cargo run --bin jet-cli -- runtimes list

# Update or install official runtime packages
cargo run --bin jet-cli -- runtimes update all

3. Start `jet-server`

Generate the required environment variables or export them:

export JET_RATE_LIMIT_HMAC_KEY_ID="my-key-id"
export JET_RATE_LIMIT_HMAC_SECRET="super-secure-shared-secret-key"
export JET_ADMIN_ALLOWED_USER_IDS="admin-user-1,admin-user-2"
export JET_SERVER_PORT=4000

# Start server
cargo run --release --bin jet-server

Alternatively, use jet-cli to run the server directly:

cargo run --bin jet-cli -- server run --release

REST API Reference

Authentication (HMAC-SHA256)

Protected endpoints (/jobs, /admin/*) require the following canonical HMAC-SHA256 headers:

Header	Description
`x-jet-auth-version`	Protocol version (must be `"2"`).
`x-jet-key-id`	Key ID matching `JET_RATE_LIMIT_HMAC_KEY_ID`.
`x-jet-user-id`	Caller identity (used for rate limiting and admin checks).
`x-jet-timestamp`	UNIX timestamp in seconds (must be within tolerance).
`x-jet-nonce`	Unique random string per request (replay protection).
`x-jet-content-sha256`	SHA256 hex digest of the raw request payload body.
`x-jet-signature`	Hexadecimal HMAC-SHA256 signature.

Canonical signature payload:

jet-hmac-v2
<key_id>
<timestamp>
<nonce>
<METHOD>
<path>
<query_string>
<content_sha256>
<content_type>
<user_id>

Note: jet-cli automatically calculates and attaches these HMAC headers to every request.

Endpoints

Method	Path	Auth	Description
`GET`	`/health`	Public	Healthcheck probe (returns `"ok"`).
`GET`	`/stats`	Public	Real-time server metrics, queue depth, uptime, in-flight jobs.
`GET`	`/runtimes`	Public	Returns list of all installed language runtimes and manifests.
`GET`	`/runtimes/{language}`	Public	Detailed manifest and aliases for a specific language.
`POST`	`/jobs`	Signed	Submit a code execution job (asynchronous, returns `202 Accepted`).
`GET`	`/jobs/{id}`	Signed	Poll status and fetch execution results for a submitted job.
`GET`	`/admin/queue-depth`	Admin	Fetch current maximum queue depth limit.
`PUT`	`/admin/queue-depth`	Admin	Dynamically adjust queue depth limit (`{"max_queue_depth": N}`).
`DELETE`	`/admin/queue-depth`	Admin	Remove queue depth cap (unlimited queue).
`POST`	`/admin/interrupt`	Admin	Preempt and interrupt in-flight jobs (`{"restart": false}`).

Job Submission Example

Request: POST /jobs

{
  "language": "python",
  "version": "latest",
  "files": [
    {
      "name": "solution.py",
      "content": "import sys\nnum = int(sys.stdin.read().strip())\nprint(num * num)"
    }
  ],
  "stdin": "12\n",
  "args": [],
  "run_timeout": 3000,
  "run_memory_limit": 536870912,
  "testcases": [
    {
      "id": "case-1",
      "input": "5\n",
      "expected_output": "25\n"
    },
    {
      "id": "case-2",
      "input": "9\n",
      "expected_output": "81\n"
    }
  ]
}

Response: 202 Accepted

{
  "job_id": "7f8b9e1c-5d2a-4f8a-9e1b-3c4d5e6f7a8b",
  "status": "QUEUED",
  "resolved_version": "3.14.3"
}

Job Polling & Result Schema

Request: GET /jobs/7f8b9e1c-5d2a-4f8a-9e1b-3c4d5e6f7a8b

Response: 200 OK

{
  "job_id": "7f8b9e1c-5d2a-4f8a-9e1b-3c4d5e6f7a8b",
  "status": "COMPLETED",
  "language": "python",
  "version": "3.14.3",
  "result": {
    "language": "python",
    "version": "3.14.3",
    "compile": null,
    "run": {
      "status": "SUCCESS",
      "exit_code": 0,
      "signal": null,
      "stdout": "144\n",
      "stderr": "",
      "memory_usage": 15425536,
      "cpu_time": 32000,
      "execution_time": 42
    },
    "testcases": [
      {
        "id": "case-1",
        "passed": true,
        "actual_output": "25\n",
        "run_details": {
          "status": "SUCCESS",
          "exit_code": 0,
          "stdout": "25\n",
          "stderr": "",
          "memory_usage": 15200000,
          "cpu_time": 28000,
          "execution_time": 38
        }
      },
      {
        "id": "case-2",
        "passed": true,
        "actual_output": "81\n",
        "run_details": {
          "status": "SUCCESS",
          "exit_code": 0,
          "stdout": "81\n",
          "stderr": "",
          "memory_usage": 15210000,
          "cpu_time": 29000,
          "execution_time": 39
        }
      }
    ]
  },
  "error": null
}

CLI Tool (`jet-cli`)

Jet comes with a developer and operations CLI tool, jet-cli.

Execute Code

Submit one or more source files for immediate execution:

# Execute Python code
jet-cli exec python -f examples/python/hello_world.py

# Execute with STDIN input and custom limits
jet-cli exec c -f examples/c/basic_math.c --stdin input.txt --run-timeout-ms 2000 --run-memory-bytes 67108864

# Multi-file compilation
jet-cli exec rust -f src/main.rs -f src/lib.rs --version latest

Load Benchmarking

Run high-throughput concurrency benchmarks against a running Jet server:

jet-cli benchmark python -f examples/python/hello_world.py \
  --concurrency 10 \
  --requests 500 \
  --delay 200ms

Outputs detailed performance metrics including:

Total execution time
Realized throughput (requests / second)
Average latency & P95 latency percentiles
Error diagnostics on failure

Runtime Management

# Display installed and cataloged runtimes
jet-cli runtimes list

# Install a specific language version
jet-cli runtimes install python 3.14.3 --arch x86_64

# Update all runtimes from upstream sources
jet-cli runtimes update all

# Clean dangling temporary downloads and caches
jet-cli runtimes clean

Server Operations

# Inspect or set max queue depth dynamically
jet-cli server queue-depth --set 500
jet-cli server queue-depth --set unlimited

# Generate a production systemd service configuration file
jet-cli server generate-systemd --output /etc/systemd/system/jet-server.service --user jet

Testing & Smoke Tests

Running Unit & Integration Tests

# Run all workspace unit tests
cargo test

# Run sandbox security integration tests (requires Linux root or unprivileged user namespaces)
cargo test --package jet-server --test sandbox_security

Automated Smoke Test Suite

Jet includes an automated end-to-end smoke test suite in scripts/smoke_test.sh that validates all core features, error handling, and security protections:

# Ensure server is running at http://localhost:4000
./scripts/smoke_test.sh

Tests performed:

Health and statistics metrics endpoints.
Single-run and testcase-based program execution.
STDIN piping and multi-file source packaging.
Limit enforcement: Time Limit Exceeded (TLE), Memory Limit Exceeded (MLE), Output Limit Exceeded (OLE).
Security defense: Fork Bomb / PID limit containment.
Error handling: Compilation failure formatting and Runtime error isolation.

Licensing

Jet is licensed under a dual-licensing model:

Open Source: GNU Affero General Public License v3 only (AGPL-3.0-only).
Commercial License: If your organization requires closed-source SaaS integration, proprietary distribution, enterprise warranties, or indemnification, a commercial license is available without copyleft obligations.

See COMMERCIAL-LICENSE.md or contact harshith.doddipalli@outlook.com for details.

Navigation Menu

Repository navigation

About

Repository files navigation

Jet ⚡

Table of Contents

Key Features

Architecture

Workspace Crates & Apps

Supported Runtimes & Languages

Security & Sandboxing Model

Prerequisites

Installation & Building

Configuration

Environment Variables

Example `jet.toml`

Running Jet

1. Start Redis

2. Manage Runtimes with `jet-cli`

3. Start `jet-server`

REST API Reference

Authentication (HMAC-SHA256)

Endpoints

Job Submission Example

Job Polling & Result Schema

CLI Tool (`jet-cli`)

Execute Code

Load Benchmarking

Runtime Management

Server Operations

Testing & Smoke Tests

Running Unit & Integration Tests

Automated Smoke Test Suite

Licensing

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
apps		apps
crates		crates
examples		examples
scripts		scripts
vendor/libcgroups		vendor/libcgroups
.gitignore		.gitignore
COMMERCIAL-LICENSE.md		COMMERCIAL-LICENSE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

Jet ⚡

Table of Contents

Key Features

Architecture

Workspace Crates & Apps

Supported Runtimes & Languages

Security & Sandboxing Model

Prerequisites

Installation & Building

Configuration

Environment Variables

Example jet.toml

Running Jet

1. Start Redis

2. Manage Runtimes with jet-cli

3. Start jet-server

REST API Reference

Authentication (HMAC-SHA256)

Endpoints

Job Submission Example

Job Polling & Result Schema

CLI Tool (jet-cli)

Execute Code

Load Benchmarking

Runtime Management

Server Operations

Testing & Smoke Tests

Running Unit & Integration Tests

Automated Smoke Test Suite

Licensing

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Example `jet.toml`

2. Manage Runtimes with `jet-cli`

3. Start `jet-server`

CLI Tool (`jet-cli`)