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

# Quickstart

> From nothing to a running sandbox in one command, then the same thing from code.

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    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:

    ```bash theme={null}
    npx nativesandbox --version
    ```

    <Note>
      Under **nvm**, a global install lands in the current Node version's directory, so switching
      versions hides `nsbx` until you install it there too.
    </Note>
  </Step>

  <Step title="Run something">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Check the host">
    ```bash theme={null}
    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:

    ```bash theme={null}
    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](/cli/doctor) for the full check list.
  </Step>

  <Step title="Install the library">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Create a sandbox and run a command">
    ```ts theme={null}
    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](/guides/sandboxes).

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

  <Step title="Move files in and out">
    ```ts theme={null}
    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.
  </Step>

  <Step title="Clean up">
    ```ts theme={null}
    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:

    ```bash theme={null}
    nsbx ls
    nsbx rm job-1
    ```
  </Step>
</Steps>

## What happens when you create a sandbox

1. The image is pulled if it is not already cached — slow the first time, instant afterwards.
2. A workspace directory is created on the host and bind-mounted at `/workspace`.
3. A container starts with your memory, CPU and PID limits applied through cgroups, every Linux
   capability dropped, and no-new-privileges set.
4. 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.
5. 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

```ts theme={null}
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();
}
```

## Next

<CardGroup cols={2}>
  <Card title="Requirements" icon="server" href="/getting-started/requirements">
    What the host needs, and how to prove it has it.
  </Card>

  <Card title="The CLI" icon="terminal" href="/cli/doctor">
    doctor, setup, run, ls, exec, rm, sweep.
  </Card>

  <Card title="Isolation" icon="shield-halved" href="/guides/isolation">
    What is taken away from every sandbox.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/sandboxes">
    Every option and method.
  </Card>
</CardGroup>