The Problem

Applications that run user‑supplied or agent‑generated code need an isolated execution environment that guarantees no interference with the host or other workloads. The platform must provide a clean lifecycle, asynchronous operation handling, and a data‑plane for streaming command output while remaining easy to integrate via a REST API.

What This Does

SPACE supplies a pluggable sandbox runtime built on Firecracker microVMs. The HTTP API lets a caller create a sandbox from a template, run arbitrary commands, stream output, and manage lifecycle events (pause, resume, delete). The core Rust services are split into several independent binaries:

  • admin/cli (crates/apps/admin/cli/src/main.rs) – a CLI for operators to manage templates, warm pools, and credentials.
  • api/svc (crates/apps/api/svc/src/main.rs) – the public HTTP façade that routes sandbox operations to the underlying manager.
  • builder/cli (crates/apps/builder/cli/src/main.rs) – builds and pushes template images for the cluster controller.
  • builder/svc (crates/apps/builder/svc/src/main.rs) – a background worker that watches a Git repository for new templates and builds them on demand.
  • cluster/controller/svc (crates/apps/cluster/controller/svc/src/main.rs) – the Kubernetes‑native controller that allocates VMs, manages warm pools, and implements lifecycle callbacks.

The platform also ships a React/Next.js UI in ui/ and a set of agent plugins (.agents/plugins/…) that demonstrate how to use the API from higher‑level agents.

How It Is Wired

Entry Point – crates/apps/api/svc/src/main.rs boots an Actix/Web server, loads configuration from Cargo.toml + docs/installation.md, and registers HTTP handlers. API Flow – A request to /sandboxes triggers api::handlers::create_sandbox, which calls sandbox::manager::create. Sandbox Manager – sandbox::manager (in crates/apps/cluster/controller/svc/src/manager.rs) orchestrates a Firecracker instance via firecracker::api. It writes sandbox metadata to the embedded SQLite database located in db/. Command Session – When /commands is POSTed, api::handlers::run_command invokes session::start, which attaches to the VM’s serial console and streams output through a WebSocket endpoint defined in api::handlers::stream. Lifecycle Ops – pause, resume, delete map to sandbox::manager::{pause, resume, delete}. The operation ID returned is stored in the database and polled by the caller. Wide‑Blast‑Radius Points – sandbox::manager is the single hub; changes to VM allocation logic or to the Firecracker API surface will ripple across all services. The database layer in db/ is another central dependency; its schema is defined in db/schema.rs. No cycles were detected in the dependency graph; each service imports only the crates it needs.

How To Use It

Setup – Install Rust 1.75+ and Docker. Build all binaries:

cargo build --workspace --release

Configuration – Edit docs/installation.md for host prerequisites and supply ~/.config/space/space.yaml (the sample is in docs/installation.md). Running the API –

target/release/space-api-svc

Operator CLI –

target/release/space-admin-cli login
target/release/space-admin-cli create-template --name my-template

First Sandbox –

curl -X POST http://localhost:8080/sandboxes \
  -H 'Content-Type: application/json' \
  -d '{"template":"my-template","commands":[{"cmd":["/bin/echo","hello"]}]}'

Real‑World Use

A data‑science platform can offload Jupyter notebook code to SPACE. The notebook server issues a POST /sandboxes with the notebook’s working directory mounted as a template, runs the notebook kernel inside the VM, and streams results back via the API. The operator can pre‑warm a pool of notebooks with space-admin-cli warm-pool.

Code Health & Issues

  • Tests – 1,204 test files (tests/…).
  • CI – ci/Dockerfile.ci and GitHub Actions workflow in .github/workflows/.
  • License – Apache‑2.0 (LICENSE).
  • No structural red flags – static analysis reports no missing tests, no hard‑coded secrets, and all modules compile.
  • Observability – telemetry hooks in crates/apps/observability/ expose OpenTelemetry spans.

The Bottom Line

SPACE is a mature, Rust‑centric sandbox runtime that cleanly separates the HTTP façade, VM orchestration, and operator tooling. Its modular crates make targeted changes straightforward, though the manager remains the central hub. Ideal for teams needing isolated code execution for agents or user workspaces, especially where Kubernetes or Firecracker is already in the stack.