SPACE README

The project's README from github.com/perplexityai/SPACE. As one markdown file: README.md.

SPACE

License: Apache 2.0

Guide · API Reference

SPACE (Sandboxed Platform for Agentic Code Execution) is a sandbox platform for running code in isolated Firecracker microVMs. Applications use its HTTP API to create Linux environments, execute commands, collect output, and manage sandbox lifecycles.

Use SPACE when your application needs a separate execution environment for an agent, a user workspace, or a code-running job. Your application decides what to run and what results to keep; SPACE manages the sandbox, its processes, and the connection carrying command output.

How it works

A template supplies the starting environment. A sandbox is an instance of that environment with its own VM and writable filesystem; multiple commands can run in the same sandbox.

Your application
    |
    +-- Create sandbox from template --> Wait for readiness
    |
    +-- Create command session --------> Attach to start the process
    |                                    Read output and exit result
    |
    +-- Keep, pause, or suspend --------> Wake when needed
    |
    +-- Delete sandbox

Sandbox lifecycle changes are asynchronous: the API returns an operation ID that you poll for completion. Command output uses a separate data-plane connection and a session-scoped attachment token.

Get started

Follow Installation and configuration to deploy SPACE in a local Kind cluster and authenticate. Then follow Your first sandbox to run a command and collect its output. The setup guide covers Kubernetes; the architecture guide also explains how SPACE can run without it.

Documentation

Read the hosted Guide and API Reference online. Both update automatically after changes merge. The links below point to source documentation in this checkout.

Guide What you will learn
Versioning and compatibility Release progression, supported guests, service stability, and upgrade/rollback requirements.
Architecture How templates, sandboxes, processes, sessions, and operations relate; what pause and suspend preserve; how the services fit together.
Installation and configuration Host prerequisites, local Kind deployment, configuration defaults, authentication, verification, and teardown.
Operator CLI API access, port forwarding, space-admin-cli login, nodes, warm pools, and system-template builds.
Your first sandbox A complete API workflow, command customization, output handling, inspection, and deletion.
E2B Compatibility Wrapper Configure ECW, create a compatibility API key, use the tested E2B Python SDK, and understand supported behavior and limitations.
API reference Endpoints, request and response fields, and examples.
Troubleshooting Local setup, authentication, lifecycle operations, command streams, and safe retries.
Operator egress profiles Configure named policy additions for federated native and ECW creates.
Observability Telemetry build features, the Rust/Go selector contract, and unchanged image defaults.
Warm pools Keep booted sandboxes ready on Kubernetes so creates skip a cold boot.
Base snapshots Restore sandboxes from a snapshot on a single node, optionally with a node warm pool.

Build documentation locally

To browse the guide and API together locally, install mdBook 0.4.52 and the API build prerequisites. From a clean checkout, run:

bash scripts/build-docs.sh
python3 -m http.server 8000 --bind 127.0.0.1 --directory target/docs/site

Open http://127.0.0.1:8000. The build also requires Git and Python 3.11+. The standalone commands remain bash scripts/build-guide-docs.sh and bash scripts/build-api-docs.sh; they also support local uncommitted edits.

The API serves its generated reference at /openapi-m1.json, with request fields, response schemas, and errors.

SPACE API

The SPACE API manages sandbox lifecycles, runs and controls processes, and streams their output. Fields marked incubating in the schema are outside the supported contract.

SPACE is implemented in Rust, but applications interact with it over HTTP and server-sent events. You do not need to embed a Rust library to use it; the first-sandbox walkthrough runs a standard-library-only Python example. Installation and cluster diagnostics use Bash.

Development

See DEPENDENCIES.md when adding or updating third-party code.

After local installation, run tilt up from the repository root to rebuild affected images and roll their workloads as files change. The Kind runbook covers this development loop, local topology, and template builds.

Use focused unit tests for component logic and the Kind smoke suites for runtime behavior. For setup-specific diagnostics, see host-path troubleshooting and template-build debugging.

Repository layout

crates/apps/            CLI tools and service binaries
crates/libs/            Shared Rust libraries
docs/                   Architecture, setup, API walkthrough, and troubleshooting
examples/               Runnable API examples without an SDK dependency
proto/                  gRPC protobuf definitions
templates/firecracker/  Seed builder and template recipes
scripts/                Utility scripts and smoke suites (scripts/tests/)
docker/                 Service Dockerfiles and Rust artifact build
ci/                     CI checks and artifact build scripts
infra/space/kind/        Local Kind configuration, bootstrap, and development runbook
infra/space/aws/reference/  Reference EKS deployment, applied on a schedule

License

SPACE is licensed under the Apache License, Version 2.0.

See CONTRIBUTING.md to propose changes or contribute.

For native API contract, concurrency, recovery, and quarantine coverage, see Native API hardening.

SPACE (perplexityai/SPACE)

Searching Database…

1.1K ·GitHub
SPACE
What is this?SPACE (Sandboxed Platform for Agentic Code Execution) is a sandbox platform that runs agent and user code inside isolated Firecracker microVMs, controlled through an HTTP API.
Is SPACE a library I embed, or a service I run?It is a self-hosted service you deploy (on Kubernetes) and talk to over HTTP/server-sent events; even though SPACE itself is written in Rust, you don't embed any Rust code to use it.
How do I get it running?Follow the Installation and configuration guide to deploy SPACE in a local Kind cluster and authenticate, then follow 'Your first sandbox' to run a command through the API and collect its output.
Do I need Kubernetes before I start?The documented setup path deploys SPACE into a local Kind (Kubernetes) cluster, and the dev loop uses 'tilt up' to rebuild and roll affected images as you change files.
Can I run it without Kubernetes?The main setup guide only covers Kubernetes; the architecture doc mentions an alternative non-Kubernetes mode exists but it's not the documented default path.
What is the E2B Compatibility Wrapper (ECW)?ECW lets you reuse the tested E2B Python SDK against SPACE by configuring a compatibility API key, with documented supported behavior and limitations.
How does the sandbox lifecycle work?A template defines the starting environment, and a sandbox is a VM instance of it with its own writable filesystem; lifecycle changes are asynchronous and return an operation ID you poll until completion.
What are warm pools and base snapshots for?Warm pools keep booted sandboxes ready on Kubernetes so new creates skip a cold boot, while base snapshots restore a sandbox from a saved snapshot on a single node, optionally combined with a node warm pool.
How is command output streamed back to my app?Command output travels over a separate data-plane connection using a session-scoped attachment token, kept apart from the control-plane API calls.
What are similar projects?smolvm, agentbox, capsule-fs, CubeSandbox, daytona, monty, OpenSandbox, quicksand
Which topics is it in?code-execution, agent-sandbox, sse, sandboxing, virtual-machine, infrastructure, sandbox, kubernetes, agents, rest-api, rust, agent
Creator
perplexityai
Size
22.8 MB
Stars
1.1K
Updated
CommitOct 16
Age
15d
Commits · 90 Days