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

# Create Sandbox

> Create a new isolated sandbox sandbox.

Provisions a new sandbox VM through the orchestrator. The API waits until the VM
reports a guest IP address before returning — typically 1–5 seconds. The returned
object contains tokens and connection details needed by the SDK.

## Request Body

<ParamField body="template" type="string">
  Template name to base the sandbox on. Becomes the sandbox `name` and is
  prefixed with `tpl-` for the `template_id`. Defaults to an empty string
  (which uses the default base image).

  Example: `"base"`
</ParamField>

<ParamField body="timeout" type="integer">
  Auto-kill timeout in seconds. When the timeout expires the sandbox state is
  set to `killed` and the VM is terminated. Pass `0` to disable auto-kill.

  Example: `300`
</ParamField>

<ParamField body="envs" type="object">
  Environment variables to inject into the sandbox VM. Keys and values must
  be strings.

  Example: `{ "OPENAI_API_KEY": "sk-..." }`
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value metadata stored with the sandbox. Useful for tagging
  sandboxes by project, run ID, or agent name.

  Example: `{ "project": "my-agent", "run_id": "run-001" }`
</ParamField>

<Note>
  Resource allocation (vCPUs, memory, disk) is fixed at the **template** level —
  the request-level `resources` field is currently rejected with HTTP 403. Use
  templates to size sandboxes instead.
</Note>

<ParamField body="network" type="object">
  Outbound network access controls.

  <Expandable title="NetworkConfig fields">
    <ParamField body="allow_out" type="string[]">
      Domains or CIDR ranges allowed for outbound traffic. Wildcards supported.
      Example: `["pypi.org", "*.github.com"]`
    </ParamField>

    <ParamField body="deny_out" type="string[]">
      Domains or CIDR ranges explicitly denied. Takes precedence over `allow_out`.
      Example: `["169.254.169.254"]`
    </ParamField>

    <ParamField body="allow_public_traffic" type="boolean" default="true">
      When `false`, all outbound traffic is denied unless explicitly in `allow_out`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="security" type="object">
  Full SecurityPolicy object (PII config, injection defense, transformation rules,
  audit config). Passed as a JSON object and stored verbatim. See the
  [Security](/security/overview) section for the complete schema.
</ParamField>

<ParamField body="lifecycle" type="object">
  Controls what happens when the sandbox timeout fires.

  <Expandable title="LifecycleConfig fields">
    <ParamField body="on_timeout" type="string">
      Action to take on timeout. Currently `"kill"` is the only supported value.
    </ParamField>

    <ParamField body="auto_resume" type="boolean" default="false">
      Automatically resume a paused sandbox when accessed.
    </ParamField>
  </Expandable>
</ParamField>

## Response

Returns a [Sandbox](/api-reference/sandbox/get) object with state `running`.

<ResponseField name="sandbox_id" type="string">
  Unique sandbox identifier. Format: `sbx-<8 chars>`.
</ResponseField>

<ResponseField name="template_id" type="string">
  Template ID used. Format: `tpl-<name>`.
</ResponseField>

<ResponseField name="state" type="string">
  Always `"running"` on a freshly created sandbox.
</ResponseField>

<ResponseField name="envd_access_token" type="string">
  Bearer token for direct envd daemon access. Used internally by the SDK.
</ResponseField>

<ResponseField name="traffic_access_token" type="string">
  Bearer token for the security proxy. Used internally by the SDK.
</ResponseField>

<ResponseField name="guest_ip" type="string">
  Internal IP address of the sandbox VM.
</ResponseField>

<ResponseField name="envd_port" type="integer">
  Port on which envd listens. Typically `49983`.
</ResponseField>

<ResponseField name="started_at" type="string">
  UTC timestamp of sandbox creation.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.declaw.ai/sandboxes \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "template": "base",
      "timeout": 300,
      "envs": { "MY_VAR": "hello" }
    }'
  ```

  ```python Python theme={null}
  from declaw import Sandbox

  sbx = Sandbox.create(
      api_key="YOUR_API_KEY",
      domain="api.declaw.ai",
      timeout=300,
      envs={"MY_VAR": "hello"},
  )
  print(sbx.sandbox_id)  # sbx-a1b2c3d4
  ```

  ```typescript TypeScript theme={null}
  import { Sandbox } from "@declaw/sdk";

  const sbx = await Sandbox.create({
    apiKey: "YOUR_API_KEY",
    domain: "api.declaw.ai",
    timeout: 300,
    envs: { MY_VAR: "hello" },
  });
  console.log(sbx.sandboxId); // sbx-a1b2c3d4
  ```
</CodeGroup>

```json Response theme={null}
{
  "sandbox_id": "sbx-a1b2c3d4",
  "template_id": "tpl-base",
  "name": "base",
  "state": "running",
  "timeout": 300,
  "envs": { "MY_VAR": "hello" },
  "envd_access_token": "envd-ab12cd34",
  "sandbox_domain": "declaw.dev",
  "traffic_access_token": "traffic-ef56gh78",
  "guest_ip": "172.16.0.5",
  "envd_port": 49983,
  "started_at": "2024-01-15T10:30:00Z",
  "end_at": "2024-01-15T10:35:00Z"
}
```

## Error Responses

| Status | Cause                                                                                                                   |
| ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid request body or malformed `security` JSON                                                                       |
| `401`  | Missing or invalid API key                                                                                              |
| `402`  | Wallet (sandbox or guardrails) has insufficient balance                                                                 |
| `403`  | Per-sandbox tier limits exceeded (vCPU / memory / disk / session duration), or request-level `resources` field supplied |
| `429`  | Concurrent sandbox limit reached for your tier, or sandbox create rate limit exceeded                                   |
| `503`  | Orchestrator is unavailable or the VM failed to start                                                                   |