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. Registry host must be public and allowlisted (registry-1.docker.io, ghcr.io, quay.io, public.ecr.aws; extend with K7_REGISTRY_ALLOWLIST)
backend (string | null): kata-firecracker-devmapper (kfd), kata-qemu-longhorn (kql), or k7d. Auto-detected when omitted
sidecar (string | null): Sidecar type, e.g. docker
root_disk_size (string, default 10Gi): Longhorn root PVC size (kql only)
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
entrypoint / cmd (string[] | null): Override image ENTRYPOINT / CMD
limits (object): Resource limits/requests; keys supported: cpu, memory, ephemeral-storage
egress_whitelist (string[] | [] | null): omit / null = open; [] = block-all; listed CIDRs or FQDNs = allowlist. See Networking
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, backend, node, 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 On kql, scales the sandbox Deployment to 0 and optionally creates a Longhorn VolumeSnapshot of its root PVC. On k7d, freezes the live VM in place (memory survives). --snapshot / the snapshot body field is 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 On kql, scales the Deployment back to 1 (PVC re-attaches). On k7d, restarts the vCPU loop — in-memory state survives.

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 sandbox into a new name. kql: disk-only clone from a VolumeSnapshot of the source’s root PVC (~45 s single-node; longer with replicas ≥ 2). k7d: warm CoW fork of disk and memory (~2–4 s to a Ready pod; child inherits running processes). kfd: returns 400. The request blocks until the new sandbox is usable.

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