Sandbox commands

Every command accepts --root, --prefix and --socket. These pages write nsbx, which is what a global install gives you; npx nativesandbox works identically in every example below.

Getting the command

npm install nativesandbox does not put nsbx on your shell’s PATH. npm links a package’s binaries into node_modules/.bin, which is on PATH inside npm scripts and npx — not in your terminal. Three ways to run it:

# Puts `nsbx` and `nativesandbox` on your PATH. What these docs assume.
npm install -g nativesandbox
nsbx doctor

# Downloads and runs it. Nothing is left behind.
npx nativesandbox doctor

# Anywhere the package is a dependency, npx finds the local copy.
npm install nativesandbox
npx nsbx doctor

Under nvm, a global install lands in the current Node version’s directory — switch versions and nsbx is gone until you install it there too. npx nativesandbox sidesteps that, at the cost of a slower first run.

Inside a project, a package.json script needs no prefix at all, because npm puts node_modules/.bin on PATH for scripts:

{ "scripts": { "sandbox:doctor": "nsbx doctor --deep" } }

`run`

nsbx run "npm install && npm test"

Creates a throwaway sandbox, runs the command, streams output as it is produced, then removes the sandbox. Exits with the command’s own status, so it composes with anything:

nsbx run "npm test" && echo "green"

Flag	Default
`--name <n>`	`run-<pid>`	Name it, so `--keep` leaves something you can `exec` into
`--runtime <r>`	`node`	`node` or `python`
`--image <ref>`	—	An explicit image, overriding `--runtime`
`--memory <MiB>`	`512`
`--cpus <n>`	`1`	Fractional allowed
`--network none`	bridge	Cut the sandbox off from the network entirely
`--keep`	off	Leave it behind instead of removing it

# A build that cannot phone home, in a box that is gone afterwards.
nsbx run --network none --memory 2048 "npm ci --ignore-scripts"

`exec`

nsbx exec build "cat dist/report.txt"

Runs a command in a sandbox that already exists, streaming as run does. Use it with a sandbox your application created, or one run --keep --name left behind.

`ls`

nsbx ls

  NAME   STATE    IMAGE           AGE  IDLE  MAX LIFE
  build  running  node:22-alpine  4m   300s  3600s
  tests  exited   node:22-alpine  2h   300s  3600s

IDLE and MAX LIFE are read off each container, not from this process — so they are what that sandbox will actually be reclaimed by, even if another process created it. Only sandboxes with the matching prefix are listed. A container this package did not create is never shown and never touched.

`rm`

nsbx rm build tests
nsbx rm --all

Removes the container and its workspace. Not reversible — use stop semantics from the library if you want the cache kept. Removing something that is already gone is reported, not an error.

`sweep`

nsbx sweep

Runs both housekeeping passes once: stop everything past its idle timeout, retire everything past its maximum lifetime. Neither touches a sandbox with a command in flight, and neither deletes a workspace.

  stopped  tests
  retired  old-build  (workspaces kept)
done 1 stopped, 1 retired

Useful from cron on a host where the application is not long-lived enough to sweep for itself.

Exit codes


`0`	It worked
the command’s own	`run` and `exec` pass it through, so `exit 42` inside gives you `42`
`1`	It failed — no engine, no such sandbox, a check that did not pass
`2`	You typed it wrong. Distinct from `1` so a script can tell them apart

Getting started

CLI

Guides

Operations

Getting the command

`run`

`exec`

`ls`

`rm`

`sweep`

Exit codes

​Getting the command

​run

​exec

​ls

​rm

​sweep

​Exit codes

Getting the command

`run`

`exec`

`ls`

`rm`

`sweep`

Exit codes