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

# Sandboxes

> Create, list, get, and delete sandboxes

## Create sandbox

Endpoint: `POST /api/v1/sandboxes`

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "$BASE/api/v1/sandboxes" \
    -H "X-API-Key: $K7_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "my-sandbox",
      "image": "alpine:latest",
      "namespace": "default",
      "limits": {"cpu": "500m", "memory": "512Mi"}
    }'
  ```
</RequestExample>

Body example:

```json theme={null}
{
  "name": "my-sandbox",
  "image": "alpine:latest",
  "namespace": "default",
  "limits": {"cpu": "500m", "memory": "512Mi"}
}
```

Body example with egress whitelist (safe pattern: proxy IP only):

```json theme={null}
{
  "name": "my-restricted-sandbox",
  "image": "alpine:latest",
  "namespace": "default",
  "egress_whitelist": ["10.0.0.5/32"],
  "limits": {"cpu": "500m", "memory": "512Mi"}
}
```

<ResponseExample>
  ```json Success theme={null}
  {
    "data": {
      "name": "my-sandbox",
      "namespace": "default",
      "image": "alpine:latest"
    }
  }
  ```
</ResponseExample>

### Request body schema

Fields accepted in the JSON body when creating a sandbox:

* `name` (string, required): Unique sandbox name in the namespace
* `image` (string, required): Container image, e.g. `alpine:latest`
* `namespace` (string, default `default`): Kubernetes namespace
* `env_file` (string | null): Path (on API host) to `.env` file to inject as Secret
* `before_script` (string, default empty): Shell commands to run before the container is marked Ready
* `limits` (object): Resource limits/requests; keys supported: `cpu`, `memory`, `ephemeral-storage`
* `egress_whitelist` (string\[] | \[] | null): See Egress section below
* `pod_non_root` (boolean, default false): Run pod as non-root (UID/GID/FSGroup 65532)
* `container_non_root` (boolean, default false): Run container as non-root (UID 65532)
* `cap_drop` (string\[] | null): List of capabilities to drop; default policy is `ALL`
* `cap_add` (string\[] | null): List of capabilities to add back

### Responses

* `201 Created` with Location header to the created resource:

```json theme={null}
{ "data": { "name": "my-sandbox", "namespace": "default", "image": "alpine:latest" } }
```

* `400 BadRequest` when validation fails (invalid limits, bad env file, already exists, etc.)

## List sandboxes

Endpoint: `GET /api/v1/sandboxes`

<ParamField query="namespace" type="string" default="default">Namespace</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -H "X-API-Key: $K7_API_KEY" "$BASE/api/v1/sandboxes?namespace=default"
  ```
</RequestExample>

Returns list of sandbox objects with fields: name, namespace, status, ready, restarts, age, image, error\_message.

<ResponseExample>
  ```json Success theme={null}
  {
    "data": [
      {
        "name": "my-sandbox",
        "namespace": "default",
        "status": "Running",
        "ready": "True",
        "restarts": 0,
        "age": "0:05:42",
        "image": "alpine:latest",
        "error_message": ""
      }
    ]
  }
  ```
</ResponseExample>

## Get sandbox

Endpoint: `GET /api/v1/sandboxes/{name}`

<ParamField path="name" type="string" required>Sandbox name</ParamField>
<ParamField query="namespace" type="string" default="default">Namespace</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -H "X-API-Key: $K7_API_KEY" "$BASE/api/v1/sandboxes/my-sandbox?namespace=default"
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "data": {
      "name": "my-sandbox",
      "namespace": "default",
      "status": "Running",
      "ready": "True",
      "restarts": 0,
      "age": "0:05:42",
      "image": "alpine:latest",
      "error_message": ""
    }
  }
  ```
</ResponseExample>

## Delete sandbox

Endpoint: `DELETE /api/v1/sandboxes/{name}`

<ParamField path="name" type="string" required>Sandbox name</ParamField>
<ParamField query="namespace" type="string" default="default">Namespace</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE -H "X-API-Key: $K7_API_KEY" \
    "$BASE/api/v1/sandboxes/my-sandbox?namespace=default"
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  { "data": { "message": "Sandbox my-sandbox deleted successfully" } }
  ```
</ResponseExample>

## Delete all sandboxes

Endpoint: `DELETE /api/v1/sandboxes`

<ParamField query="namespace" type="string" default="default">Namespace</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE -H "X-API-Key: $K7_API_KEY" \
    "$BASE/api/v1/sandboxes?namespace=default"
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "data": {
      "message": "Deleted 1 sandboxes",
      "results": [ { "name": "my-sandbox", "success": true, "error": null } ]
    }
  }
  ```
</ResponseExample>

<Warning>
  Deleting sandboxes is irreversible.
</Warning>

## See also

* API Security & networking: `/api/security`