@computesdk/sandbox0
Sandbox0 provider for ComputeSDK. Create fast persistent sandboxes, run shell commands, and use native filesystem operations through the official Sandbox0 JavaScript SDK.
Installation
npm install computesdk @computesdk/sandbox0
Setup
Create a team API key and export it:
export SANDBOX0_TOKEN=your_sandbox0_token
SANDBOX0_BASE_URL is optional and defaults to the public Sandbox0 API at
https://api.sandbox0.ai. For automated team workloads, set it to the team's
home-region endpoint so requests go directly to the regional gateway.
An interactive access token can also be used by setting both
SANDBOX0_TOKEN and SANDBOX0_TEAM_ID.
Usage
import { compute } from 'computesdk';
import { sandbox0 } from '@computesdk/sandbox0';
compute.setConfig({
provider: sandbox0({
token: process.env.SANDBOX0_TOKEN,
hardTtl: 600,
}),
});
const sandbox = await compute.instances.create({
templateId: 'coding-agent',
memory: 256,
});
const result = await sandbox.runCommand('node --version');
console.log(result.stdout);
await sandbox.filesystem.writeFile('/tmp/hello.txt', 'Hello from Sandbox0');
console.log(await sandbox.filesystem.readFile('/tmp/hello.txt'));
await sandbox.destroy();
Configuration
| Option | Environment variable | Default | Description |
|---|---|---|---|
token | SANDBOX0_TOKEN or SANDBOX0_API_KEY | required | Team API key, or an access token when teamId is set |
teamId | SANDBOX0_TEAM_ID | none | Team ID required with access-token authentication |
baseUrl | SANDBOX0_BASE_URL | SDK default | Sandbox0 API endpoint |
templateId | SANDBOX0_TEMPLATE | coding-agent | Template used for new sandboxes |
ttl | - | platform default | Soft runtime TTL in seconds |
hardTtl | - | platform default | Hard sandbox TTL in seconds |
memory | - | template default | Memory in MiB or a quantity such as 1Gi |
envs | - | none | Default environment variables |
commandTimeout | - | none | Default command timeout in milliseconds |
Per-create templateId, snapshotId, memory, envs, ttl, hardTtl, and autoResume options override provider defaults where applicable. Numeric memory values are interpreted as MiB.
Feature support
| Feature | Supported |
|---|---|
| Create / getById / list / destroy | Yes |
| Shell commands | Yes, through sh -lc |
Command cwd, environment, timeout, and background mode | Yes |
| Filesystem | Yes, through Sandbox0's native file API |
| Public URLs | Yes, for public services already configured on the sandbox |
| Restore from snapshot | Yes, with snapshotId at create time |
| Snapshot management | Use the native Sandbox0 SDK |
Foreground runCommand calls start an asynchronous Sandbox0 Context, follow
its WebSocket terminal event, and read the final result from the Context API.
If the WebSocket disconnects, the provider polls the Context until it exits.
The command timeout is also applied as the Context TTL, and a timed-out call
attempts to delete the Context.
destroy is idempotent and retries short-lived throttling or server failures. Setting hardTtl is still recommended for automated workloads so a failed client cannot leave a sandbox indefinitely.
For Sandbox0-specific capabilities such as pause/resume, services, snapshots, volumes, and observability, call sandbox.getInstance() to access the native sandbox0 SDK handle.
License
MIT