Shared provider contracts for sandbox-backed agent runtimes.
This package is intentionally implementation-free. It defines the boundary
between core runtime code and sandbox providers, while provider packages such
as @agent-harness-experimental/sandbox-vercel, @agent-harness-experimental/sandbox-daytona, and
@agent-harness-experimental/sandbox-just-bash own platform-specific behavior.
Type-level API documentation lives in the JSDoc comments in
src/index.ts.
Architecture
The sandbox layer is split into three responsibilities:
Core runtime code chooses a provider, checks capabilities, calculates
adapter runtime needs, and starts bridges or split-mode operations.
The interface package defines the provider contract and shared neutral
shapes for commands, files, layouts, resources, templates, and network
policies.
Provider packages translate that neutral contract into platform-specific
API calls, filesystem layout, process lifecycle, and network controls.
Core code should not know about provider paths, binary names, snapshot fields,
or control-plane quirks. Those details belong in the provider package and are
surfaced through getLayout, capabilities, and session methods.
Provider Tiers
There are two provider tiers.
SandboxWorkspaceProvider is the minimal workspace contract. It is enough for
bounded command execution and binary-safe file IO. This is the right shape for
split/local providers that do not expose hosted ports or long-running
processes.
SandboxHostedProvider is the full hosted runtime contract. It adds
long-running process lifecycle through spawn and asynchronous hosted port
resolution through getPortUrl. Full bridge/proxy runtimes require this tier.
Provider selection must be capability-driven. A workspace-only provider can be
accepted for split mode when no proxy or hosted port is needed, but it must be
rejected before startup for hosted bridge/proxy flows.
Runtime Layout
Providers own layout decisions. The runtime asks for a SandboxLayout and then
uses those returned paths for:
user workspace operations
bridge state
SDK session metadata
provider helper files
proxy config, binaries, and certificates when applicable
This keeps core runtime code portable across Vercel, Daytona, just-bash, and
future providers.
Command Model
The interface intentionally separates bounded and long-running execution.
exec is for commands that should complete and return collected output.
spawn is only available on hosted workspaces and is for bridges, proxies, and
other processes that need logs, waiting, and explicit termination.
This split prevents workspace-only providers from pretending to support hosted
process lifecycle through shell backgrounding.
Files
File IO is binary-safe at the interface boundary. Providers should preserve
bytes when uploading and downloading, regardless of whether their native API is
path-based, tar/archive-based, or in-memory.
Templates And Resources
The interface uses neutral resource and template language. Providers map
cpu, memoryGiB, diskGiB, and template references to their own platform
terms such as snapshots, images, classes, or presets.
Public core APIs should not expose provider-specific source names unless the
caller is explicitly configuring a specific provider package.
Network Policy
Network policy support is capability-gated. Providers advertise the native
features they can enforce, such as deny-all, CIDR allow lists, host allow
lists, header transforms, and dynamic updates.
When a requested policy cannot be enforced natively, provider selection or the
provider implementation should fail clearly unless core is intentionally
handling that feature through the proxy layer.
Adding A Provider
A provider package should:
implement the narrowest provider tier it can honestly satisfy
keep platform-specific paths and bootstrap details in the provider package
map neutral session creation options into provider-native API calls
implement binary-safe file reads and writes
advertise only capabilities it actually supports
reject unsupported network, template, process, or port features explicitly
add focused tests for capability gating and provider-specific mappings