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

# POST Create a sandbox

> Deploy a repo branch or PR into an isolated sandbox with twins

```bash theme={null}
POST /sandboxes
```

Creates a repo-backed sandbox deployment for a branch or PR. Use this when you want to deploy your app or agent into an isolated sandbox, attach selected twins, seed those twins from a scenario, and inject environment variables into the deployed process.

**Request body**

| Field             | Type            | Required    | Description                                                                                                                                                          |
| ----------------- | --------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `repo`            | `string`        | Yes         | Repository in `owner/repo` format.                                                                                                                                   |
| `branch`          | `string`        | Conditional | Branch to deploy. Required unless `pr_url` is provided.                                                                                                              |
| `pr_url`          | `string`        | Conditional | Pull request URL to deploy. Required unless `branch` is provided.                                                                                                    |
| `twins`           | `array<string>` | No          | Twins to include. When omitted, Arga can use the scenario's twins or detected runtime profile.                                                                       |
| `scenario_id`     | `string`        | No          | Saved scenario or preset id used to seed twins.                                                                                                                      |
| `scenario_prompt` | `string`        | No          | Natural-language seed prompt. Used when `scenario_id` is omitted.                                                                                                    |
| `ttl_minutes`     | `integer`       | No          | Sandbox TTL, 1-480 minutes. Defaults to 60. Free-plan accounts are capped at the free-tier TTL limit; requests above the cap are rejected by plan-limit enforcement. |
| `env`             | `object`        | No          | Extra environment variables to inject into the deployed app. These override generated twin env vars on key conflict.                                                 |

In production, the authenticated user must have the GitHub integration connected. `twins` must be supported twin names from the runtime catalog; invalid names return `400`.

**Response**

Queued sandboxes return empty connection details until deployment is ready:

```json theme={null}
{
  "sandbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "app_url": null,
  "twins": {},
  "env_vars": {}
}
```

When ready, poll [Get a sandbox](/api-reference/get-get-a-sandbox) to retrieve `app_url`, per-twin URLs, and env vars.

```json theme={null}
{
  "sandbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "ready",
  "app_url": "https://a1b2c3d4-app.preview.argalabs.com",
  "twins": {
    "gmail": {
      "base_url": "https://a1b2c3d4-gmail.preview.argalabs.com",
      "admin_url": "https://a1b2c3d4-gmail.internal.argalabs.com",
      "env_vars": {
        "GMAIL_ACCESS_TOKEN": "ya29.gmail-twin-owner",
        "GMAIL_API_BASE_URL": "https://a1b2c3d4-gmail.preview.argalabs.com"
      }
    }
  },
  "env_vars": {
    "GMAIL_ACCESS_TOKEN": "ya29.gmail-twin-owner",
    "GMAIL_API_BASE_URL": "https://a1b2c3d4-gmail.preview.argalabs.com"
  }
}
```