Documentation

JavaScript / TypeScript: sandboxes

Create a Linux workspace that keeps its state between commands.

Before you run it

Follow the SDK quickstart to install the package and set BOLTZLABS_API_KEY. All SDK calls that make requests are asynchronous.

Create a sandbox and run commands

sandbox.js

import { Sandbox } from 'boltzlabs';

const sandbox = await Sandbox.create({ environment: 'node', name: 'web' });
try {
  await sandbox.waitUntilRunning(); // creation returns before boot completes
  const result = await sandbox.exec('node -e "console.log(42)"');
  console.log(result.stdout);
  result.check(); // throws when the command exits non-zero
} finally {
  await sandbox.delete(); // stops compute billing
}

Command results expose stdout, stderr, exitCode, durationMs and ok. A non-zero exit is returned as a result; call check() to throw.

Automatic cleanup

cleanup.js

await Sandbox.withSandbox({ environment: 'node' }, async (sandbox) => {
  await sandbox.waitUntilRunning();
  console.log(String(await sandbox.exec('echo hello')));
}); // deleted even if the callback throws

Copy files, pause and resume

workspace.js

// Use an existing sandbox from Sandbox.create().
await sandbox.push('./src', '/workspace'); // uploaded as /workspace/src
await sandbox.pull('/workspace/src', './download');

await sandbox.pause();
await sandbox.resume();
await sandbox.waitUntilRunning();

await sandbox.delete();

Keep files you need after a pause under /workspace. Packages installed elsewhere may not survive restoration onto another machine.

Fork a sandbox

fork.js

const branch = await sandbox.fork({ name: 'try-b' }); // a new sandbox, same files
await branch.exec('git checkout -b try-b');           // the original is untouched

A fork copies everything under /workspace. Running processes and packages installed elsewhere are not copied. A fork is a sandbox of its own: it counts toward your concurrent limit and is billed until you pause or delete it.

Port URLs and metrics

ports.js

// Once your service is listening inside the sandbox:
console.log(sandbox.url(8080));
console.log(await sandbox.metrics());

The port URL uses the public BoltzLabs origin. Set internet: true when creating a sandbox if your workload needs outbound internet access.

List sandboxes and available options

listing.js

import { me, sandboxes, sandbox, environments, machines } from 'boltzlabs';

console.log(await me());
console.log(await sandboxes());
const existing = await sandbox('your-sandbox-id');
console.log(await environments());
console.log(await machines());