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

# Create Sandbox

> Create a new sandbox from a template using the HopX Control Plane API. Provision isolated cloud environments with custom configuration, resources, and environment variables. Learn how to use POST /v1/sandboxes endpoint with Python and JavaScript SDK examples.

Create a new sandbox from a template. The sandbox will be provisioned with resources (vCPU, memory, disk) defined by the template.

## Endpoint

```
POST /v1/sandboxes
```

## Request

### Headers

```
Authorization: Bearer $HOPX_API_KEY
Content-Type: application/json
```

### Body Parameters

| Parameter         | Type              | Required | Description                                   |
| ----------------- | ----------------- | -------- | --------------------------------------------- |
| `template_id`     | string or integer | Yes\*    | Template ID to use                            |
| `template_name`   | string            | Yes\*    | Template name (alternative to `template_id`)  |
| `region`          | string            | No       | Preferred region (e.g., `us-east`, `eu-west`) |
| `timeout_seconds` | integer           | No       | Auto-kill timeout in seconds                  |
| `internet_access` | boolean           | No       | Enable internet access (default: `true`)      |
| `env_vars`        | object            | No       | Environment variables to set in sandbox       |

<Note>
  Either `template_id` or `template_name` must be provided. Resources (vcpu, memory, disk) are **always loaded from the template** - you cannot specify custom resources.
</Note>

### Example Request

```bash theme={null}
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "73",
    "timeout_seconds": 3600,
    "internet_access": true,
    "env_vars": {
      "MY_VAR": "my_value",
      "API_KEY": "secret123"
    }
  }'
```

<Note>
  Replace `$HOPX_API_KEY` with your actual API key from [console.hopx.dev](https://console.hopx.dev), or set it as an environment variable: `export HOPX_API_KEY="your-API key-here"`
</Note>

Or using template name:

```bash theme={null}
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "code-interpreter",
    "timeout_seconds": 3600
  }'
```

<Note>
  Replace `$HOPX_API_KEY` with your actual API key from [console.hopx.dev](https://console.hopx.dev), or set it as an environment variable: `export HOPX_API_KEY="your-API key-here"`
</Note>

## Response

### Success (201 Created)

```json theme={null}
{
  "id": "sandbox_abc123xyz",
  "object": "sandbox",
  "status": "running",
  "public_host": "https://sandbox_abc123xyz.hopx.dev",
  "direct_url": "https://sandbox_abc123xyz.hopx.dev",
  "template_id": "73",
  "template_name": "code-interpreter",
  "organization_id": 123,
  "node_id": "node_xyz789",
  "region": "us-east",
  "resources": {
    "vcpu": 2,
    "memory_mb": 4096,
    "disk_mb": 10240
  },
  "internet_access": true,
  "timeout_seconds": 3600,
  "expires_at": "2025-01-29T00:00:00Z",
  "created_at": "2025-01-28T00:00:00Z",
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_expires_at": "2025-01-28T01:00:00Z",
  "request_id": "req_abc123"
}
```

### Response Fields

| Field              | Type   | Description                                          |
| ------------------ | ------ | ---------------------------------------------------- |
| `id`               | string | Sandbox ID (use for all subsequent operations)       |
| `status`           | string | Current sandbox status (`creating`, `running`, etc.) |
| `public_host`      | string | VM Agent API base URL for this sandbox               |
| `direct_url`       | string | Alternative VM Agent API URL (same as `public_host`) |
| `template_id`      | string | Template ID used to create sandbox                   |
| `template_name`    | string | Template name                                        |
| `resources`        | object | Allocated resources (from template)                  |
| `auth_token`       | string | JWT token for VM Agent API authentication            |
| `token_expires_at` | string | ISO 8601 timestamp when token expires                |

## Status Codes

| Code  | Description                                               |
| ----- | --------------------------------------------------------- |
| `201` | Sandbox created successfully                              |
| `400` | Invalid request (missing template, invalid timeout, etc.) |
| `401` | Authentication required                                   |
| `402` | Payment required (insufficient balance)                   |
| `404` | Template not found                                        |
| `503` | Service unavailable (no available nodes)                  |

## Errors

### Template Not Found (404)

```json theme={null}
{
  "error": "Template not found",
  "code": "RESOURCE_NOT_FOUND",
  "request_id": "req_abc123"
}
```

**Cause:** The specified `template_id` or `template_name` doesn't exist.

**Fix:** List available templates using `GET /v1/templates` to find valid template IDs or names.

### Invalid Request (400)

```json theme={null}
{
  "error": "Invalid request: timeout_seconds must be positive",
  "code": "INVALID_REQUEST",
  "request_id": "req_abc123"
}
```

**Cause:** Invalid parameter value (e.g., negative timeout, missing template).

**Fix:** Verify all parameters meet requirements:

* `timeout_seconds` must be positive
* Either `template_id` or `template_name` must be provided
* `env_vars` must be a valid object

### Service Unavailable (503)

```json theme={null}
{
  "error": "Service unavailable: no available nodes",
  "code": "SERVICE_UNAVAILABLE",
  "request_id": "req_abc123"
}
```

**Cause:** No compute nodes are available to provision the sandbox.

**Fix:** Retry the request after a few moments. This is usually temporary.

## Use Cases

### Quick Code Execution

Create a sandbox for quick code execution:

```bash theme={null}
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "code-interpreter",
    "timeout_seconds": 300
  }'
```

### Long-Running Job

Create a sandbox for a long-running task:

```bash theme={null}
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "73",
    "timeout_seconds": 7200,
    "env_vars": {
      "DATABASE_URL": "postgres://...",
      "API_KEY": "secret"
    }
  }'
```

### Region-Specific Deployment

Create a sandbox in a specific region:

```bash theme={null}
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "code-interpreter",
    "region": "eu-west"
  }'
```

## Related

* **SDK**: [Sandbox.create()](/sdk/python/sandbox#create) - Python SDK method
* **[Get Sandbox](/api/control-plane/get-sandbox)** - Retrieve sandbox information
* **[List Sandboxes](/api/control-plane/list-sandboxes)** - Query all your sandboxes
* **[VM Agent API](/api/vm-agent/overview)** - Execute code in your new sandbox
* [CLI Sandbox Commands](/cli/commands/sandbox) - Manage sandboxes from CLI

## Next Steps

* **[Get Sandbox](/api/control-plane/get-sandbox)** - Retrieve sandbox information
* **[List Sandboxes](/api/control-plane/list-sandboxes)** - Query all your sandboxes
* **[VM Agent API](/api/vm-agent/overview)** - Execute code in your new sandbox