Beam Cloud
A sandbox per Beam Cloud container. Fast, GPU-capable sandboxes with snapshots, via @beamcloud/beam-js.
Installation
@beamcloud/beam-js is an optional peer dependency of sbox-sdk, loaded lazily on first use.
pnpm add sbox-sdk @beamcloud/beam-jsUsage
import { createSandboxClient } from "sbox-sdk";
import { beam } from "sbox-sdk/beam";
const client = createSandboxClient({
provider: beam({
token: process.env.BEAM_TOKEN!,
workspaceId: process.env.BEAM_WORKSPACE_ID!,
}),
});
const sandbox = await client.create({
template: "python:3.12",
resources: { vcpus: 2, memoryMB: 2048, gpu: "A10G" }, // GPU is first-class
});
const res = await sandbox.commands.run("nvidia-smi");
console.log(res.stdout);
const snap = await sandbox.snapshots!.create();
const forks = await sandbox.snapshots!.fork(2); // boot 2 from the snapshottemplate is a base image. Sandboxes are real Linux containers with coreutils.
exec takes { cwd, env } natively (perCommandEnvCwd: true) and the adapter
buffers the process streams (streaming emulated). The SDK's file helpers are
local-path based, so files.read/files.write go through exec + base64
(binary-safe). Ports are public SSL endpoints (exposePort). snapshots.create()
is instance.snapshot() and fork() snapshots then boots N sandboxes via
createFromSnapshot — in-place restore is not supported. setTimeout() maps
to updateTtl; list isn't exposed by the SDK.
Authentication
An API token + workspace id.
| Option | Env var | Required | Description |
|---|---|---|---|
token | BEAM_TOKEN | required | Beam API token. |
workspaceId | BEAM_WORKSPACE_ID | required | Beam workspace id. |
image | — | optional | Default base image when a spec omits `template`. |
Token and workspace fall back to the standard Beam environment when the options are omitted.
Options
Prop
Type
Capabilities
| Capability | Level | Notes |
|---|---|---|
gpu | native | resources.gpu |
snapshot / fork | native | snapshot() + createFromSnapshot |
setTimeout | native | updateTtl |
exposePort | native | public SSL endpoint |
filesUpload | native | via exec + base64 |
streaming | emulated | buffered process streams |
list | unsupported | not exposed by the SDK |
pause / stop | unsupported | destroy() = terminate |
perCommandEnvCwd is true; previewModel is subdomain. In-place snapshot restore reports NotSupported.