Quickstart

Install the CLI

npm install -g nativesandbox

That gives you nsbx. There is no binary to download and no runtime to install — the container engine already on your host is the runtime.Or skip the install entirely and prefix every command with npx nativesandbox instead:

npx nativesandbox --version

Under nvm, a global install lands in the current Node version’s directory, so switching versions hides nsbx until you install it there too.

Run something

nsbx run "node --version"

That creates a sandbox, runs the command, streams the output back and removes the sandbox. If it fails, the next step says why.

Check the host

nsbx doctor

info platform     Linux 6.14.0 arm64
info socket       /run/user/1001/podman/podman.sock  (Podman's per-user socket)

   ✓ container engine         reachable, version 4.9.3
   ✓ podman socket            active
   ✓ lingering                on — survives logout
   ✓ cgroup delegation        cpu memory pids
   ✓ subuid / subgid          present
   ✓ user namespaces          enabled
   ✓ /dev/kvm                 absent, and not required

done This host can run sandboxes.

Anything it finds, it explains and offers to fix:

nsbx setup

setup prints each command, says whether it needs root, and waits for you to agree before running it. Nothing happens to your machine that you have not seen first. See the CLI for the full check list.

Install the library

npm install nativesandbox

Node 22 or newer. Zero runtime dependencies. This is the library, separate from the CLI in step 1 — a project depends on it, rather than installing it globally.

Create a sandbox and run a command

import { Sandboxes, MiB } from "nativesandbox";

const sandboxes = new Sandboxes({ root: "/var/tmp/sandboxes" });

const box = await sandboxes.create("job-1", {
  runtime: "node",
  memory: MiB(512),
  cpus: 1,
});

const result = await box.exec("node --version");
console.log(result.stdout);      // v22.11.0

The name is yours and is how you find the sandbox again. Calling create() with the same name returns the same sandbox while its shape still serves the request — see sandboxes.

memory is a branded type, so memory: 512 will not compile. Write the unit — MiB(512), GiB(2) — and the ambiguity between megabytes, mebibytes and bytes cannot reach the engine.

Move files in and out

await box.writeFile("/src/main.js", "console.log(41 + 1)");

const { stdout } = await box.exec("node src/main.js");   // "42\n"

const built = await box.readFile("/dist/bundle.js");     // Buffer
box.exists("/dist/bundle.js");                           // true

These are host reads and writes, because the workspace is a bind mount rather than a channel to a guest. box.workspaceDir is the directory on the host, and reading it is reading the sandbox.

Clean up

await box.stop();                   // keeps the workspace; the next create() starts it again
await sandboxes.remove("job-1");    // removes the container AND the workspace
sandboxes.close();                  // stops the housekeeping timer

Or from the terminal:

nsbx ls
nsbx rm job-1

What happens when you create a sandbox

The image is pulled if it is not already cached — slow the first time, instant afterwards.
A workspace directory is created on the host and bind-mounted at /workspace.
A container starts with your memory, CPU and PID limits applied through cgroups, every Linux capability dropped, and no-new-privileges set.
It idles on sleep infinity, so every later command is an exec into the same sandbox and whatever the last command installed is still there.
If it goes quiet for five minutes it stops, keeping the workspace. After an hour it is retired and rebuilt fresh over the same warm workspace.

Steps 4 and 5 are why reuse is worth having: the second npm install in a sandbox is free.

A complete example

import { Sandboxes, GiB, SandboxError } from "nativesandbox";

const sandboxes = new Sandboxes({ root: "/var/tmp/sandboxes" });

try {
  const box = await sandboxes.create("build", { memory: GiB(1), cpus: 2 });
  await box.writeFile("/package.json", JSON.stringify({ name: "x", version: "1.0.0" }));

  const install = await box.exec("npm install --silent", {
    timeoutMs: 180_000,
    onFrame: ({ data }) => process.stdout.write(data),   // stream it, do not wait
  });
  if (install.code !== 0) throw new Error(install.stderr);

  console.log(await box.readFile("/package-lock.json"));
} catch (error) {
  if (error instanceof SandboxError && error.code === "unavailable") {
    console.error("the engine went away mid-run");
  }
  throw error;
} finally {
  await sandboxes.remove("build");
  sandboxes.close();
}

Requirements

What the host needs, and how to prove it has it.

The CLI

doctor, setup, run, ls, exec, rm, sweep.

Isolation

What is taken away from every sandbox.

API reference

Every option and method.

Getting started

CLI

Guides

Operations

What happens when you create a sandbox

A complete example

Next

Requirements

The CLI

Isolation

API reference

​What happens when you create a sandbox

​A complete example

​Next

Requirements

The CLI

Isolation

API reference

What happens when you create a sandbox

A complete example

Next