k7/docs/api/endpoints/sandboxes.mdx

---
title: "Sandboxes"
description: "Create, list, get, and delete sandboxes"
---

## Create sandbox

Endpoint: `POST /api/v1/sandboxes`

<RequestExample>
```bash cURL
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
{
  "name": "my-sandbox",
  "image": "alpine:latest",
  "namespace": "default",
  "limits": {"cpu": "500m", "memory": "512Mi"}
}
```

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

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

<ResponseExample>
```json Success
{
  "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
{ "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
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
{
  "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
curl -H "X-API-Key: $K7_API_KEY" "$BASE/api/v1/sandboxes/my-sandbox?namespace=default"
```
</RequestExample>

<ResponseExample>
```json Success
{
  "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
curl -X DELETE -H "X-API-Key: $K7_API_KEY" \
  "$BASE/api/v1/sandboxes/my-sandbox?namespace=default"
```
</RequestExample>

<ResponseExample>
```json Success
{ "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
curl -X DELETE -H "X-API-Key: $K7_API_KEY" \
  "$BASE/api/v1/sandboxes?namespace=default"
```
</RequestExample>

<ResponseExample>
```json Success
{
  "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`