> ## Documentation Index
> Fetch the complete documentation index at: https://nativesandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox commands

> run, exec, ls, rm and sweep — the fleet from a terminal.

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:

<CodeGroup>
  ```bash Global theme={null}
  # Puts `nsbx` and `nativesandbox` on your PATH. What these docs assume.
  npm install -g nativesandbox
  nsbx doctor
  ```

  ```bash No install theme={null}
  # Downloads and runs it. Nothing is left behind.
  npx nativesandbox doctor
  ```

  ```bash In a project theme={null}
  # Anywhere the package is a dependency, npx finds the local copy.
  npm install nativesandbox
  npx nsbx doctor
  ```
</CodeGroup>

<Note>
  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.
</Note>

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

```json theme={null}
{ "scripts": { "sandbox:doctor": "nsbx doctor --deep" } }
```

## `run`

```bash theme={null}
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:

```bash theme={null}
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                    |

```bash theme={null}
# A build that cannot phone home, in a box that is gone afterwards.
nsbx run --network none --memory 2048 "npm ci --ignore-scripts"
```

## `exec`

```bash theme={null}
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`

```bash theme={null}
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`

```bash theme={null}
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`

```bash theme={null}
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 |