Sandboxes

Create sandbox

Endpoint: POST /api/v1/sandboxes

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"}
  }'

Body example:

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

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

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

{
  "data": {
    "name": "my-sandbox",
    "namespace": "default",
    "image": "alpine:latest"
  }
}

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:

{ "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

string

default:"default"

Namespace

curl -H "X-API-Key: $K7_API_KEY" "$BASE/api/v1/sandboxes?namespace=default"

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

{
  "data": [
    {
      "name": "my-sandbox",
      "namespace": "default",
      "status": "Running",
      "ready": "True",
      "restarts": 0,
      "age": "0:05:42",
      "image": "alpine:latest",
      "error_message": ""
    }
  ]
}

Get sandbox

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

string

required

Sandbox name

string

default:"default"

Namespace

curl -H "X-API-Key: $K7_API_KEY" "$BASE/api/v1/sandboxes/my-sandbox?namespace=default"

{
  "data": {
    "name": "my-sandbox",
    "namespace": "default",
    "status": "Running",
    "ready": "True",
    "restarts": 0,
    "age": "0:05:42",
    "image": "alpine:latest",
    "error_message": ""
  }
}

Delete sandbox

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

string

required

Sandbox name

string

default:"default"

Namespace

curl -X DELETE -H "X-API-Key: $K7_API_KEY" \
  "$BASE/api/v1/sandboxes/my-sandbox?namespace=default"

{ "data": { "message": "Sandbox my-sandbox deleted successfully" } }

Delete all sandboxes

Endpoint: DELETE /api/v1/sandboxes

string

default:"default"

Namespace

curl -X DELETE -H "X-API-Key: $K7_API_KEY" \
  "$BASE/api/v1/sandboxes?namespace=default"

{
  "data": {
    "message": "Deleted 1 sandboxes",
    "results": [ { "name": "my-sandbox", "success": true, "error": null } ]
  }
}

Deleting sandboxes is irreversible.

Get logs

Endpoint: GET /api/v1/sandboxes/{name}/logs Returns a snapshot of the pod’s container logs. Live follow streaming isn’t shipped yet — use k7 --core logs --follow ... on a cluster node for tail-and-follow until API streaming lands.

string

required

Sandbox name

string

default:"default"

Namespace

string

default:"sandbox"

Container name inside the pod

int

default:"200"

Number of trailing lines to return

int

default:"0"

Only return entries newer than N seconds (0 = no filter)

curl -H "X-API-Key: $K7_API_KEY" \
  "$BASE/api/v1/sandboxes/demo/logs?tail=100"

{ "data": { "logs": "first line\nsecond line\n..." } }

Responses:

200 OK with {"data": {"logs": "..."}} on success.
404 NotFound when no pod matches the sandbox name in the namespace.

Pause sandbox

Endpoint: POST /api/v1/sandboxes/{name}/pause Scales the sandbox Deployment to 0 and optionally creates a Longhorn VolumeSnapshot of its root PVC for crash-consistent state capture (kata-qemu-longhorn only).

string

required

Sandbox name

Body (all keys optional):

{
  "namespace": "default",
  "snapshot": "demo-v1"
}

When snapshot is set, the API snapshots the sandbox’s root PVC under that name using the longhorn VolumeSnapshotClass. The PVC name is derived server-side (<sandbox>-root-lh for kata-qemu-longhorn) — there is no client-side flag for it. Without snapshot the endpoint only scales to 0 without taking a snapshot.

curl -X POST -H "X-API-Key: $K7_API_KEY" -H "Content-Type: application/json" \
  "$BASE/api/v1/sandboxes/demo/pause" \
  -d '{"snapshot":"demo-v1"}'

{ "data": { "message": "Sandbox demo paused (replicas=0). Snapshot demo-v1 created." } }

Resume sandbox

Endpoint: POST /api/v1/sandboxes/{name}/resume Scales the Deployment back to 1.

string

required

Sandbox name

Body:

{ "namespace": "default" }

curl -X POST -H "X-API-Key: $K7_API_KEY" -H "Content-Type: application/json" \
  "$BASE/api/v1/sandboxes/demo/resume" -d '{}'

{ "data": { "message": "Sandbox demo resumed (replicas=1)." } }

Fork sandbox

Endpoint: POST /api/v1/sandboxes/{name}/fork Clones a kata-qemu-longhorn sandbox into a new name with its own disk derived from a fresh VolumeSnapshot of the source’s root PVC. The request blocks until the new PVC is bound (typically ~45 s today). Fork is kata-qemu-longhorn only — fork on a kata-firecracker-devmapper sandbox returns 400.

string

required

Source sandbox name

Body:

{
  "new_name": "demo-clone",
  "namespace": "default",
  "snapshot": "optional-temp-snap-name"
}

new_name is required. snapshot is an optional name for the fork-time intermediate snapshot; if omitted, k7 picks one.

curl -X POST -H "X-API-Key: $K7_API_KEY" -H "Content-Type: application/json" \
  "$BASE/api/v1/sandboxes/demo/fork" \
  -d '{"new_name":"demo-clone"}'

{
  "data": {
    "name": "demo-clone",
    "namespace": "default",
    "source": "demo",
    "message": "Forked sandbox demo -> demo-clone with cloned disk (PVC demo-clone-root-lh from snapshot demo-to-demo-clone-snap) in 44.92s"
  }
}

Responses:

201 Created with Location: /api/v1/sandboxes/{new_name}?namespace={namespace}
400 BadRequest when new_name is missing, or the source backend doesn’t support fork
404 NotFound when the source Deployment or its root PVC is missing
409 Conflict when new_name already exists in the namespace

Getting started

Concepts

Using Katakate

API overview

API endpoints

Create sandbox

Request body schema

Responses

List sandboxes

Get sandbox

Delete sandbox

Delete all sandboxes

Get logs

Pause sandbox

Resume sandbox

Fork sandbox

See also

​Create sandbox

​Request body schema

​Responses

​List sandboxes

​Get sandbox

​Delete sandbox

​Delete all sandboxes

​Get logs

​Pause sandbox

​Resume sandbox

​Fork sandbox

​See also

Create sandbox

Request body schema

Responses

List sandboxes

Get sandbox

Delete sandbox

Delete all sandboxes

Get logs

Pause sandbox

Resume sandbox

Fork sandbox

See also