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

# Agent Sandbox

> Deploy and configure the sandbox that runs agent code, code-execution nodes, and plugins

Anything on the platform that runs code — the agent **Sandbox** and **Code Execution** tools, code-execution flow nodes, plugin nodes, and the [`/v1/sandboxes` API](/api-reference/v1--sandboxes/create-sandbox) — executes inside an isolated **sandbox**. As an operator you choose which sandbox **backend** runs that code, trading isolation strength against infrastructure requirements.

## Backends

The platform picks a backend in two layers: a **remote** sandbox-manager service (preferred), falling back to a **local** in-worker backend when the remote is off, unhealthy, or unreachable.

<CardGroup cols={2}>
  <Card title="syd → gVisor (remote, default)" icon="shield-halved">
    The remote sandbox manager runs each sandbox as a **gVisor** (`runsc`) container — a user-space kernel that intercepts syscalls, with OverlayFS and a jailed network namespace. Strong isolation; runs in Docker / Cloud Run / Kubernetes.
  </Card>

  <Card title="syd → MicroVM (remote)" icon="server">
    The remote manager can instead run each sandbox as a full **cloud-hypervisor micro-VM**. The strongest isolation, but **requires KVM** — bare-metal or nested-virtualization hosts only (not Docker).
  </Card>

  <Card title="deno (local, default fallback)" icon="js">
    An in-process **Deno** sandbox with a SQLite-backed filesystem. No Docker, no separate service — good for local dev and lightweight deployments.
  </Card>

  <Card title="subprocess / none (local)" icon="terminal">
    <b>subprocess</b> runs code in a worker-local Python subprocess (least isolation — dev only). <b>none</b> disables local execution entirely.
  </Card>
</CardGroup>

<Warning>
  `subprocess` provides no real isolation — untrusted code runs with the worker's
  privileges. Use it only in trusted local development. For any shared or
  production deployment, run the **remote sandbox manager** (gVisor or MicroVM).
</Warning>

## Choosing a backend

| You're running…                                       | Recommended backend                           |
| ----------------------------------------------------- | --------------------------------------------- |
| Production / multi-tenant                             | Remote **gVisor** (`USE_REMOTE_SANDBOX=true`) |
| Bare-metal / KVM host wanting VM-grade isolation      | Remote **MicroVM**                            |
| Local development                                     | Local **deno** (default)                      |
| A worker with no sandbox service and Deno unavailable | **subprocess** (trusted only) or **none**     |

## Configuration

The behavior is driven by environment variables read from the worker/backend settings:

| Variable                 | Default | Purpose                                                                                               |
| ------------------------ | ------- | ----------------------------------------------------------------------------------------------------- |
| `USE_REMOTE_SANDBOX`     | `true`  | Prefer the remote sandbox-manager service.                                                            |
| `REMOTE_SANDBOX_BACKEND` | `syd`   | The remote backend type. (`SANDBOX_BACKEND` is a deprecated alias; `auto`/`deno` normalize to `syd`.) |
| `LOCAL_SANDBOX_BACKEND`  | `deno`  | Local path when the remote is off/unhealthy: `deno`, `subprocess`, or `none`.                         |
| `SANDBOX_MANAGER_URL`    | —       | URL of the remote sandbox-manager service. Required when `USE_REMOTE_SANDBOX=true`.                   |
| `ADMIN_API_KEY`          | —       | Shared secret the platform sends to the manager (`X-API-Key`). **Set a strong value in production.**  |

<Info>
  When `USE_REMOTE_SANDBOX=true` but `SANDBOX_MANAGER_URL` is unset or the manager
  is unhealthy, the platform automatically falls back to `LOCAL_SANDBOX_BACKEND`,
  so code execution keeps working (with weaker isolation). Set
  `LOCAL_SANDBOX_BACKEND=none` if you'd rather fail closed.
</Info>

## Deploying the remote sandbox manager

The remote backends are served by a separate **sandbox-manager** service (the `agentsandbox` component):

* **gVisor manager** — a container image bundling `runsc` (gVisor) and a minimal Debian rootfs; exposes an HTTP control-plane on port **8000**. Deployable in Docker / Cloud Run / Kubernetes.
* **MicroVM manager** — runs on a KVM-capable host using cloud-hypervisor; HTTP control-plane on port **8400**.

Point the platform at it with `SANDBOX_MANAGER_URL` and share the `ADMIN_API_KEY`. Every control-plane call is authenticated with that key via the `X-API-Key` header, so the manager is never exposed unauthenticated.

## Security model

Regardless of runtime, sandboxes are built to contain untrusted code:

* **Isolation** — gVisor intercepts syscalls in a user-space kernel; MicroVM uses a full guest kernel. Each sandbox gets its own filesystem (OverlayFS: read-only base + per-sandbox writable layer).
* **Network jail** — private/internal ranges (RFC1918) are blocked from inside the sandbox; it can NAT out to the public internet but cannot reach internal services. (This is why the [SDK-in-sandbox](/sdk/resources/sandboxes) pattern needs a publicly reachable backend URL.)
* **Ephemeral** — non-persistent sandboxes are cleaned up when idle.
* **Permission-gated** — the `sandboxes:run` permission is required to run code and is never implied by general resource access.

<Note>
  Related reading: the [Agent Sandbox](/platform/agents/sandbox) product page (how
  agents use it) and the [Sandboxes SDK](/sdk/resources/sandboxes) /
  [Sandboxes API](/api-reference/v1--sandboxes/create-sandbox) for programmatic use.
</Note>