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-js

Usage

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 snapshot

template 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.

Authentication variables for the beam adapter.
OptionEnv varRequiredDescription
tokenBEAM_TOKENrequiredBeam API token.
workspaceIdBEAM_WORKSPACE_IDrequiredBeam workspace id.
imageoptionalDefault 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

CapabilityLevelNotes
gpunativeresources.gpu
snapshot / forknativesnapshot() + createFromSnapshot
setTimeoutnativeupdateTtl
exposePortnativepublic SSL endpoint
filesUploadnativevia exec + base64
streamingemulatedbuffered process streams
listunsupportednot exposed by the SDK
pause / stopunsupporteddestroy() = terminate

perCommandEnvCwd is true; previewModel is subdomain. In-place snapshot restore reports NotSupported.

On this page