Sandbox Runtime API

English | 简体中文

Sandbox Runtime API v0.1 is an independently designed, provider-neutral contract for creating, observing, controlling, and deleting isolated execution environments for AI agents and developer tools.

The project standardizes portable lifecycle and capability semantics. It is not a hosted sandbox platform, an agent framework, or an open-source distribution of any private system.

The access methods converge on one portable runtime boundary. Provider implementations remain replaceable behind a single SPI; the dashed future Provider is a roadmap extension, not part of the v0.1 delivery.

Why

Agent applications need similar execution primitives but encounter provider-specific APIs for lifecycle, readiness, command execution, files, terminals, networking, persistence, and recovery. This project separates those concerns into:

• a versioned sandbox resource model and lifecycle;
• a provider SPI with explicit capability negotiation;
• an embeddable in-memory reference runtime;
• a deterministic mock provider;
• provider conformance checks;
• HTTP/SSE mappings, a TypeScript client SDK, and a development CLI.

Relationship to Harness Runtime API

harness-runtime-api standardizes how an application controls an agent harness execution. Sandbox Runtime API standardizes the isolated compute environment in which a harness or its tools may run.

Application
    -> Harness Runtime API   # conversations, executions, events, approvals
    -> Sandbox Runtime API   # environments, readiness, capabilities, recovery
    -> Provider              # local, container, Kubernetes, serverless, VM

Neither API requires the other. An integration may use both when it needs portable harness and portable sandbox semantics.

v0.1 Features

Version 0.1.1 builds on the original 0.1.0 baseline and contains:

• a normative runtime model, protocol, capability vocabulary, and OpenAPI document;
• capability preflight;
• idempotent lifecycle, reconciliation, generation fencing, and recreation;
• bounded command execution and sandbox-relative file operations;
• append-only event listing and resumable SSE projection;
• an in-memory runtime, TypeScript SDK, CLI, and loopback reference server;
• Mock and unsafe Local Providers;
• a provider conformance runner;
• public-source provenance and clean-room contribution rules.

The API remains pre-1.0 and may change incompatibly. The Local Provider is not a security sandbox and must never execute untrusted code.

Quick Start

Development requirements: Node.js 22.12+ (22.x) or 24.x and pnpm 10. CI verifies both lines.

pnpm install
pnpm check
pnpm build

Continue with the Quickstart or open the documentation index.

For a prebuilt, independently installable SDK/CLI archive, use the GitHub release guide. npm registry publication is not enabled.

Repository Map

Path	Purpose
src/protocol.ts	Portable states, resources, capabilities, and errors
src/provider.ts	Provider SPI
src/runtime.ts	In-memory reference runtime
src/providers/local.ts	Unsafe local-process development Provider
src/providers/mock.ts	Deterministic development provider
src/conformance.ts	Reusable provider checks
src/server.ts / src/sdk.ts	HTTP/SSE reference server and TypeScript client
spec/	Normative model and design decisions
docs/clean-room-policy.md	Public-source and contribution boundary

Clean-room Boundary

This repository is designed only from public specifications, public repositories, and general distributed-systems principles. Contributions must not include proprietary code, private API shapes, internal identifiers, deployment configuration, production data, or non-public test cases.

Read Origin and provenance, Clean-room policy, and Non-goals before contributing.

License

Apache License 2.0.