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

# Create a sandbox

> Spin up an isolated Firecracker MicroVM in seconds, ready to run commands immediately.

`Sandbox.create()` boots a fresh VM and returns when it's ready to use. There's no readiness check or polling - the returned instance is already `active`.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  import { Sandbox } from "@superserve/sdk"

  const sandbox = await Sandbox.create({ name: "data-analyzer" })
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  from superserve import Sandbox

  sandbox = Sandbox.create(name="data-analyzer")
  ```
</CodeGroup>

## With options

Attach metadata tags, inject environment variables, cap the active lifetime, or lock down network egress at creation time.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  import { Sandbox } from "@superserve/sdk"

  const sandbox = await Sandbox.create({
    name: "data-analyzer",
    timeoutSeconds: 3600,
    metadata: { env: "prod", owner: "agent-7" },
    envVars: { LOG_LEVEL: "debug" },
    secrets: { OPENAI_API_KEY: "openai-prod" },
    network: {
      allowOut: ["api.openai.com", "*.github.com"],
      denyOut: ["0.0.0.0/0"],
    },
  })
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  from superserve import Sandbox, NetworkConfig

  sandbox = Sandbox.create(
      name="data-analyzer",
      timeout_seconds=3600,
      metadata={"env": "prod", "owner": "agent-7"},
      env_vars={"LOG_LEVEL": "debug"},
      secrets={"OPENAI_API_KEY": "openai-prod"},
      network=NetworkConfig(
          allow_out=["api.openai.com", "*.github.com"],
          deny_out=["0.0.0.0/0"],
      ),
  )
  ```
</CodeGroup>

<Note>
  Use **`secrets`** for credentials, not `envVars`. A secret binds an env var to a stored credential and attaches the real value to outbound requests — the real credential never enters the sandbox. See [Secrets](/secrets/overview).
</Note>

## Common options

| Option                                      | Type                     | Description                                                                                                                          |
| ------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `name`                                      | `string`                 | **Required.** Human-readable sandbox name.                                                                                           |
| `timeoutSeconds` / `timeout_seconds`        | `number`                 | Auto-pause after this many seconds of active time (per session; re-armed on resume). See [Lifecycle](/sandbox/lifecycle#auto-pause). |
| `autoDeleteSeconds` / `auto_delete_seconds` | `number`                 | Delete the sandbox once continuously paused for this many seconds. See [Lifecycle](/sandbox/lifecycle#auto-delete).                  |
| `metadata`                                  | `Record<string, string>` | String tags. See [Metadata](/sandbox/metadata).                                                                                      |
| `envVars` / `env_vars`                      | `Record<string, string>` | Env vars applied to every process. See [Environment variables](/sandbox/environment-variables).                                      |
| `network`                                   | `NetworkConfig`          | Egress allow/deny rules. See [Networking](/sandbox/networking).                                                                      |

See the [Sandbox reference](/sdk-reference/sandbox#sandbox-create) for every option including `apiKey`, `baseUrl`, and `signal`.

## Create from a template

Boot a sandbox from a system or team template via `fromTemplate` (name, UUID, or `Template` instance).

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const sandbox = await Sandbox.create({
    name: "my-sandbox",
    fromTemplate: "superserve/python-3.11",  // name
  })
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  sandbox = Sandbox.create(
      name="my-sandbox",
      from_template="superserve/python-3.11",
  )
  ```
</CodeGroup>

The sandbox's vCPU, memory, and disk size are inherited from the template; they cannot be overridden. See [Templates overview](/templates/overview) for how to build your own.

Next: [run commands](/commands/overview), [write files](/filesystem/read-write), or [pause the sandbox](/sandbox/lifecycle) to save costs between runs.