# Core concepts

> Sandboxes, templates, lifecycle and states, networking, persistence, snapshots, forks, browser sandboxes, and the isolation model.

## Sandbox

A **sandbox** is an isolated Linux container that runs your code. You create one, run
commands and manage files inside it, optionally preview a server running in it, and then stop
or destroy it. Each sandbox belongs to one account and is only visible to that account.

Every sandbox has:

- an `id` (`sbx_…`),
- a `status` (see [Lifecycle](#lifecycle)),
- a **template** (its base image),
- a **memory limit** and a **command timeout** (controlled by your [plan](./plans-and-limits.md)),
- a **network mode** (`bridge` or `none`),
- a `/workspace` working directory where your files live.

## Templates

A template selects the base image. All templates ship with `git`, `curl`, and
`ca-certificates` so cloning repos works out of the box.

| Template | Base | Use it for |
|----------|------|------------|
| `python` | Python (slim) | Python scripts, data work, AI agents |
| `node`   | Node.js 20 (slim) | JS/TS apps, npm tooling |
| `blank`  | Debian (slim) | Anything else; install what you need |

Choose a template when creating a sandbox: `{"template":"python"}`. If you omit it, the
default base image is used. Need your own dependencies? Register a
[custom image](./sdk.md#custom-images-templates) from any registry image or a Dockerfile.

## Lifecycle

A sandbox moves through these states:

| Status | Meaning |
|--------|---------|
| `ready` | Container is up and idle, waiting for work. |
| `active` | A command is currently running in it. |
| `stopped` | Container removed, **workspace files persisted** to storage. Resume to continue. |
| `failed` | Something went wrong creating/running it. |
| `destroyed` | Permanently removed. Cannot be resumed. |

**Stop vs. destroy:**

- **Stop** (`POST /v1/sandboxes/{id}/stop`) tears down the container but archives the
  `/workspace` files to durable storage. **Resume** (`POST …/resume`) creates a fresh
  container and restores those files. Running processes and memory are **not** preserved -
  only files.
- **Destroy** (`DELETE /v1/sandboxes/{id}`) removes the sandbox for good.

**Auto-resume:** running a command or doing a file operation on a *stopped* sandbox will
automatically resume it first (restoring your files).

**Startup command:** because processes don't survive a stop, you can set a **startup command**
that the platform runs automatically on create and on every resume (after files are restored) -
so a dev server / preview comes back on its own. It takes priority over a
`/workspace/flax.startup` file (first non-empty, non-comment line). See the
[API reference](./api.md) and "Make previews survive a resume" in [Previews](./previews.md).

**Idle reclaim:** sandboxes with no activity are reclaimed automatically after an idle
timeout - **stopped** (files persisted) when storage is enabled, otherwise destroyed. A
sandbox with an in-flight asynchronous command is never reclaimed while that command runs.

## Networking

- `bridge` (default): the sandbox has outbound network access and can run servers you
  [preview](./previews.md).
- `none`: fully network-isolated - no outbound access and no previews. Use this for running
  fully untrusted code where you don't want any network.

Set it at creation: `{"template":"python","network_mode":"none"}`.

## Persistence

When object storage is configured for the platform, `/workspace` is archived on stop and
restored on resume (and via `restore_from` when creating a new sandbox). This makes sandboxes
durable across restarts while keeping the per-sandbox storage within your
[plan's limit](./plans-and-limits.md). Files are preserved; processes and RAM are not.

## Snapshots

A **snapshot** is a named, reusable capture of a sandbox's `/workspace` and sandbox configuration.
Use it when you want a prepared base environment for agents, tests, or repeated app runs:
install dependencies, write files, configure a startup command, snapshot it, then create fresh
sandboxes from that snapshot.

Snapshots are different from stop/resume:

- stop/resume continues the same sandbox id after archiving its files;
- snapshots create new sandbox ids from a reusable artifact;
- both preserve files, not running processes or RAM.

See the SDK examples: [Python](./sdk.md#filesystem-snapshots) ·
[JavaScript](./sdk-js.md#filesystem-snapshots).

## Forks

A **fork** creates a new independent sandbox from an existing sandbox's `/workspace` and sandbox
configuration. Use it when you want to branch an agent run, compare multiple eval paths, or keep a
base sandbox intact while experimenting in a copy.

Forks are different from snapshots:

- forks are immediate copies from one sandbox into one new sandbox;
- snapshots are named reusable artifacts that can create many sandboxes later;
- both preserve files and config, not running processes or RAM.

## Browser sandboxes

Browser-capable sandboxes are requested with capabilities instead of template names:

- `browser` means a Chromium-capable sandbox with CDP access.
- Bring your own agent framework by connecting to the sandbox's CDP URL (Playwright, Puppeteer,
  browser-use, Stagehand, or a custom client).

Browser sandboxes persist profile and artifacts under `/workspace/.flax/browser/`:

- `profile`
- `screenshots`
- `downloads`
- `traces`

Those files persist through stop/resume, snapshots, and forks. This is browser profile/artifact
persistence, not live browser process or memory resume: the browser can be restarted with the same
profile and artifacts. See the SDK browser helpers: [Python](./sdk.md#browser-capabilities) ·
[JavaScript](./sdk-js.md#browser-capabilities).

## Isolation (at a glance)

Sandboxes run untrusted code, so each one runs with a hardened container profile: dropped
Linux capabilities, no privilege escalation, a process-count cap, and CPU/memory limits, on top
of gVisor-hardened kernel isolation. See [Security](./security.md) for the full model and your
responsibilities.