Node.js quickstart - BoxLite Documentation

Untrusted code, agent-generated scripts, and third-party tools all run in a disposable sandbox with a hardware-virtualization boundary — stronger than a container, and far quicker to start than building a VM yourself.

Prerequisites

The @boxlite-ai/boxlite Node package and a machine with hardware virtualization — see Installation.

If the platform does not meet the virtualization requirement, the Box fails to start but the process does not crash; see Troubleshooting below.

Installation

# Note the scope: @boxlite-ai/boxlite (latest published version; check with: npm view @boxlite-ai/boxlite version)
npm install @boxlite-ai/boxlite

Make sure your package.json is an ESM project (the SDK is published as ESM only):

{
  "type": "module"
}

Quick Example

Create hello.mjs (or a .js file in a "type": "module" project); it is runnable as-is:

// hello.mjs — your first BoxLite sandbox
import { SimpleBox } from "@boxlite-ai/boxlite";

async function main() {
  // alpine:latest is small and quick to pull, suitable for smoke tests.
  // Without cpus/memoryMib, the runtime's default VM size applies.
  // Pass cpus/memoryMib explicitly to control the footprint.
  const box = new SimpleBox({ image: "alpine:latest" });

  try {
    // exec(cmd, ...args) -> { exitCode, stdout, stderr }
    const result = await box.exec("echo", "Hello from BoxLite!");

    // Important: a non-zero exit code does not raise; check exitCode yourself.
    if (result.exitCode !== 0) {
      throw new Error(`Command failed (exit ${result.exitCode}): ${result.stderr}`);
    }

    console.log("stdout:", result.stdout.trim());
    console.log("exitCode:", result.exitCode);
  } catch (err) {
    // Image pull failure / missing command, etc. raise a standard Error (not necessarily a BoxliteError).
    console.error("Execution error:", err);
    process.exitCode = 1;
  } finally {
    // The box is lazily created; stop() stops and cleans up (autoRemove defaults to true).
    await box.stop();
  }
}

main();

Run:

node hello.mjs

What happens:

On the first run, BoxLite pulls the alpine:latest OCI image (later runs hit the local cache).
The Box is lazily created and starts a microVM on the first exec().
The command runs inside the VM, collecting stdout/stderr/exit code.
stop() stops the VM and cleans up (autoRemove defaults to true).

TypeScript 5.2+: `await using` for automatic cleanup

SimpleBox implements Symbol.asyncDispose, so it calls stop() automatically when leaving scope — no try/finally needed:

// hello.ts — requires TypeScript 5.2+ (target includes Disposable)
import { SimpleBox } from "@boxlite-ai/boxlite";

async function main(): Promise<void> {
  await using box = new SimpleBox({ image: "alpine:latest" });

  const result = await box.exec("echo", "Hello!");
  if (result.exitCode !== 0) {
    throw new Error(`exit ${result.exitCode}: ${result.stderr}`);
  }
  console.log(result.stdout.trim());
  // box automatically calls stop() when leaving scope
}

main().catch((err) => {
  console.error(err);
  process.exitCode = 1;
});

Common execution variants

import { SimpleBox } from "@boxlite-ai/boxlite";

async function main() {
  const box = new SimpleBox({ image: "alpine:latest" });
  try {
    // 1) With environment variables: the second arg is the args array, the third is the env object (Record<string,string>)
    const r1 = await box.exec("sh", ["-c", "echo $MY_VAR"], { MY_VAR: "custom-value" });
    console.log("env:", r1.stdout.trim());

    // 2) With working directory / user / timeout (the fourth arg, options)
    const r2 = await box.exec(
      "sh",
      ["-c", "pwd"],
      {},
      { cwd: "/tmp", user: "root", timeoutSecs: 30 },
    );
    console.log("cwd:", r2.stdout.trim());

    // 3) box metadata (info() is a synchronous method; do not await)
    const info = box.info();
    console.log("id:", box.id, "state:", info.state.status);
  } catch (err) {
    console.error("Execution error:", err);
    process.exitCode = 1;
  } finally {
    await box.stop();
  }
}

main();

Parameters and Returns

`new SimpleBox(options)` common fields

SimpleBoxOptions (the full field list is in the SDK type definitions; the table below covers the most common):

Field	Type	Required	Description
`image`	`string`	one of two	OCI image reference, e.g. `"alpine:latest"`. Provide either `image` or `rootfsPath`
`rootfsPath`	`string`	one of two	Path to a local OCI image layout directory (the on-disk form of a container image); an alternative to `image`
`cpus`	`number`	optional	Number of vCPUs. When omitted, the runtime’s default VM size applies
`memoryMib`	`number`	optional	Memory in MiB. When omitted, the runtime’s default VM size applies
`diskSizeGb`	`number`	optional	Disk size in GB
`name`	`string`	optional	Box name; use with `reuseExisting` to reuse
`autoRemove`	`boolean`	optional	Whether to delete on stop; defaults to `true`
`reuseExisting`	`boolean`	optional	Reuse an existing Box with the same name; defaults to `false`
`workingDir`	`string`	optional	Default working directory
`env`	`Record<string, string>`	optional	Box-level environment variables
`volumes`	`{ hostPath; guestPath; readOnly? }[]`	optional	Host directory mounts. `readOnly` is a boolean (`true` = read-only), not a `"ro"/"rw"` string
`ports`	`{ hostPort?; guestPort; protocol? }[]`	optional	Port forwarding; omit `hostPort` to use the same as the guest
`network`	`NetworkSpec`	optional	`{ mode: "enabled" \| "disabled", allowNet?: string[] }`
`secrets`	`Secret[]`	optional	Outbound secret injection, `{ name, value, hosts?, placeholder? }`
`security`	`SecurityOptions`	optional	Isolation options object (Node passes an object directly; no preset static methods)

`box.exec(...)` overloads

Call form	Description
`exec(cmd, ...args)`	Command + variadic arguments
`exec(cmd, args, env)`	`args: string[]`, `env: Record<string,string>`
`exec(cmd, args, env?, options?)`	`options: { cwd?: string; user?: string; timeoutSecs?: number }`

The timeout parameter in the wrapper-layer SimpleBox.exec is called timeoutSecs (inside the options object).

`ExecResult` (the return value of `exec`)

Field	Type	Description
`exitCode`	`number`	Process exit code. A non-zero value does not raise; check it yourself
`stdout`	`string`	Standard output (collected into a string)
`stderr`	`string`	Standard error

`box.info()` return value (`JsBoxInfo`, a synchronous method)

Field	Type	Description
`id`	`string`	Box ID
`name`	`string?`	Box name
`state`	`JsBoxStateInfo`	State object containing `.status` (a string), `.running`, and `.pid?`
`image`	`string`	Image reference
`cpus` / `memoryMib`	`number`	Resource configuration

The correct path to the state string is box.info().state.status (the outer field is state, the inner field is status). info() is synchronous; do not await it. The async version is getInfo().

Troubleshooting

`Cannot find package 'boxlite'` / module not found

The package name has a scope. Both install and import must use @boxlite-ai/boxlite:

// Wrong
import { SimpleBox } from "boxlite"; // does not exist
// Correct
import { SimpleBox } from "@boxlite-ai/boxlite";

`Cannot use import statement outside a module` / `require is not defined`

The SDK is published as ESM only. Add "type": "module" to package.json, or rename the file to .mjs, and use import rather than require.

A command failed but no exception was raised

exec does not raise on a non-zero exit code; it only places the code into ExecResult.exitCode. Always check it explicitly:

const result = await box.exec("false"); // exit code 1, but does not raise
if (result.exitCode !== 0) {
  throw new Error(`exit ${result.exitCode}: ${result.stderr}`);
}

A missing command / startup failure raises a bare `Error`

When a command is not found inside the Box, or the underlying start fails, the error raised may be a standard Error (instanceof BoxliteError === false), with a message like internal error: spawn_failed: .... Do not assume the exception is always an ExecError/BoxliteError:

import { SimpleBox } from "@boxlite-ai/boxlite";

const box = new SimpleBox({ image: "alpine:latest" });
try {
  await box.exec("this-binary-does-not-exist");
} catch (err) {
  // Inspect err.message; do not catch only BoxliteError subclasses
  console.error("Command execution failed:", err.message);
} finally {
  await box.stop();
}

Image pull failure (network problem)

The first run needs network access to pull the image. On a network error or an unreachable registry, an error is raised. Catch and retry, or pull ahead of time:

try {
  await box.exec("echo", "ok");
} catch (err) {
  console.error("Image pull may have failed; check the network and retry:", err.message);
}

No hardware virtualization → the Box cannot start

Linux: confirm /dev/kvm exists and the current user is in the kvm group (ls -l /dev/kvm).
macOS Intel: not supported.
WSL2: enable KVM inside WSL.
macOS ARM64: uses Hypervisor.framework by default, no extra configuration needed.

When the start fails, an exception is raised but the Node process does not crash; place it in try/catch to handle it cleanly.

The volume `readOnly` was passed as a string

In the SDK layer, the volume read-only marker is a boolean, not the CLI’s "ro"/"rw" string:

// Wrong: "ro"/"rw" is only for the CLI
const bad = new SimpleBox({
  image: "alpine:latest",
  volumes: [{ hostPath: "/data", guestPath: "/data", readOnly: "ro" }],
});
// Correct: boolean
const good = new SimpleBox({
  image: "alpine:latest",
  volumes: [{ hostPath: "/data", guestPath: "/data", readOnly: true }], // read-only
});

Next Steps

Run the bundled SDK examples in the repository: examples/node/simplebox.js (basic execution), codebox.js (code execution sandbox), browserbox.js, computerbox.js, and interactivebox.js.
To run a Python/JS snippet and get its output directly, see CodeBox (fixed language image, run(code) in one step).
Other languages: see the Python quickstart, the Rust quickstart, and the Go quickstart.

​Prerequisites

​Installation

​Quick Example

​TypeScript 5.2+: await using for automatic cleanup

​Common execution variants

​Parameters and Returns

​new SimpleBox(options) common fields

​box.exec(...) overloads

​ExecResult (the return value of exec)

​box.info() return value (JsBoxInfo, a synchronous method)

​Troubleshooting

​Cannot find package 'boxlite' / module not found

​Cannot use import statement outside a module / require is not defined

​A command failed but no exception was raised

​A missing command / startup failure raises a bare Error

​Image pull failure (network problem)

​No hardware virtualization → the Box cannot start

​The volume readOnly was passed as a string

​Next Steps