sandboxd-o

Base URL: http://localhost:8080

Health

• GET /healthz
• Success: 200 OK

Response

{
    "ok": true
}

Node Status (Unified Heartbeat + Resources)

• GET /v1/node/status
• Success: 200 OK

Response

{
    "ok": true,
    "resources": {
        "capacity_cpu_milli": 8000,
        "capacity_memory_bytes": 33554432000,
        "allocatable_cpu_milli": 7200,
        "allocatable_memory_bytes": 30198988800,
        "used_cpu_milli": 500,
        "used_memory_bytes": 536870912,
        "available_cpu_milli": 6700,
        "available_memory_bytes": 29662117888,
        "max_alloc_percent": 90,
        "updated_at": "2026-05-14T01:00:00Z"
    }
}

Sandbox APIs

Create Sandbox

• POST /v1/sandboxes
• Body: CreateSandboxRequest
• Success: 202 Accepted (async provisioning)
• Failure: 400 Bad Request

Request

{
    "id": "sbx-http-demo",
    "egress": true,
    "ports": [
        {
            "hostPort": 30080,
            "containerPort": 8080,
            "protocol": "tcp"
        }
    ],
    "readinessProbe": {
        "protocol": "http",
        "port": 8080,
        "path": "/healthz",
        "initialDelaySeconds": 1,
        "periodSeconds": 1,
        "timeoutSeconds": 1,
        "successThreshold": 2,
        "failureThreshold": 3
    },
    "containers": [
        {
            "name": "web",
            "image": "python:3.12-alpine",
            "args": [
                "sh",
                "-c",
                "mkdir -p /tmp/www && echo sandbox-http > /tmp/www/index.html && cd /tmp/www && python -m http.server 8080"
            ],
            "env": [],
            "workDir": "",
            "resource": {
                "cpu": "250m",
                "memory": "256Mi",
                "ephemeralStorage": "96Mi"
            }
        },
        {
            "name": "worker",
            "image": "alpine:3.20",
            "args": ["sh", "-c", "while true; do sleep 60; done"],
            "env": [],
            "workDir": "",
            "resource": {
                "cpu": "100m",
                "memory": "128Mi",
                "ephemeralStorage": "96Mi"
            }
        }
    ]
}

• readinessProbe is optional.
• If provided, all fields inside readinessProbe are required.
• protocol supports tcp and http.
• If protocol is http, path is required and must start with /.
• http readiness is considered successful only for status codes in the range 200 <= code < 400.
• Readiness checks target the sandbox private endpoint (sandboxIP:port) and do not directly validate external reachability on published host ports.

Response (Accepted)

{
    "sandbox": {
        "id": "sbx-http-demo",
        "phase": "creating",
        "namespace": "k8s.io",
        "ip": "",
        "subnetCIDR": "10.89.0.0/16",
        "bridgeName": "sbx-br0",
        "egress": true,
        "ports": [
            {
                "hostPort": 30080,
                "containerPort": 8080,
                "protocol": "tcp"
            }
        ],
        "containers": {
            "web": {
                "id": "sbx-http-demo-web",
                "name": "web",
                "phase": "creating",
                "image": "python:3.12-alpine",
                "args": [
                    "sh",
                    "-c",
                    "mkdir -p /tmp/www && echo sandbox-http > /tmp/www/index.html && cd /tmp/www && python -m http.server 8080"
                ],
                "resource": {
                    "cpu": "250m",
                    "memory": "256Mi"
                },
                "taskPID": 0,
                "runtime": "runsc"
            },
            "worker": {
                "id": "sbx-http-demo-worker",
                "name": "worker",
                "phase": "creating",
                "image": "alpine:3.20",
                "args": ["sh", "-c", "while true; do sleep 60; done"],
                "resource": {
                    "cpu": "100m",
                    "memory": "128Mi"
                },
                "taskPID": 0,
                "runtime": "runsc"
            }
        },
        "cniConfPath": "/etc/cni/sandboxd.d/20-sbxnet.conflist",
        "createdAt": "2026-05-08T11:00:00Z",
        "updatedAt": "2026-05-08T11:00:00Z"
    }
}

Error Examples

{
    "error": "container web: cpu is required"
}

{
    "error": "insufficient cpu allocatable: requested=2000m used=7000m limit=7200m (90% of host)"
}

{
    "error": "insufficient memory allocatable: requested=17179869184 used=34359738368 limit=42949672960 (90% of host)"
}

{
    "error": "insufficient ip addresses in subnet 10.89.0.0/16: in_use=65534 usable=65534"
}

{
    "error": "host port already in use: 30080/tcp (sandbox sbx-old)"
}

List Sandboxes (Cursor Pagination)

• GET /v1/sandboxes?cursor=<sandbox_id>&limit=<n>
• Default limit: 20
• Max limit: 200
• Success: 200 OK

Response

{
    "items": [
        {
            "id": "sbx-http-demo",
            "phase": "running",
            "namespace": "k8s.io",
            "ip": "10.89.0.18",
            "subnetCIDR": "10.89.0.0/16",
            "bridgeName": "sbx-br0",
            "egress": true,
            "ports": [
                {
                    "hostPort": 30080,
                    "containerPort": 8080,
                    "protocol": "tcp"
                }
            ],
            "containers": {
                "web": {
                    "id": "sbx-http-demo-web",
                    "name": "web",
                    "phase": "running",
                    "image": "docker.io/library/python:3.12-alpine",
                    "resource": {
                        "cpu": "250m",
                        "memory": "256Mi"
                    },
                    "taskPID": 12345,
                    "runtime": "runsc",
                    "taskStatus": "running"
                }
            },
            "cniConfPath": "/etc/cni/sandboxd.d/20-sbxnet.conflist",
            "createdAt": "2026-05-08T11:00:00Z",
            "updatedAt": "2026-05-08T11:00:12Z"
        }
    ],
    "next_cursor": "sbx-http-demo"
}

Get Sandbox

• GET /v1/sandboxes/{id}
• Success: 200 OK
• Failure:
  • 404 Not Found (state file not found)
  • 500 Internal Server Error (store/runtime refresh error)

Response

{
    "sandbox": {
        "id": "sbx-http-demo",
        "phase": "running",
        "namespace": "k8s.io",
        "ip": "10.89.0.18",
        "subnetCIDR": "10.89.0.0/16",
        "bridgeName": "sbx-br0",
        "egress": true,
        "ports": [
            {
                "hostPort": 30080,
                "containerPort": 8080,
                "protocol": "tcp"
            }
        ],
        "containers": {
            "web": {
                "id": "sbx-http-demo-web",
                "name": "web",
                "phase": "running",
                "image": "docker.io/library/python:3.12-alpine",
                "args": [
                    "sh",
                    "-c",
                    "mkdir -p /tmp/www && echo sandbox-http > /tmp/www/index.html && cd /tmp/www && python -m http.server 8080"
                ],
                "resource": {
                    "cpu": "250m",
                    "memory": "256Mi"
                },
                "taskPID": 12345,
                "runtime": "runsc",
                "taskStatus": "running"
            },
            "worker": {
                "id": "sbx-http-demo-worker",
                "name": "worker",
                "phase": "running",
                "image": "docker.io/library/alpine:3.20",
                "args": ["sh", "-c", "while true; do sleep 60; done"],
                "resource": {
                    "cpu": "100m",
                    "memory": "128Mi"
                },
                "taskPID": 12346,
                "runtime": "runsc",
                "taskStatus": "running"
            }
        },
        "cniConfPath": "/etc/cni/sandboxd.d/20-sbxnet.conflist",
        "createdAt": "2026-05-08T11:00:00Z",
        "updatedAt": "2026-05-08T11:00:12Z"
    }
}

Batch Sandbox Status

• POST /v1/sandboxes/statuses
• Purpose: return minimal status for orchestrator synchronization with low payload.
• Max IDs per request: 200

Request

{
    "ids": ["sbx-a", "sbx-b"]
}

Response

{
    "items": [
        {
            "id": "sbx-a",
            "phase": "running",
            "error": "",
            "unhealthy_containers": []
        },
        {
            "id": "sbx-b",
            "phase": "error",
            "error": "pull image \"docker.io/library/nginx:bad\": ...",
            "unhealthy_containers": [
                {
                    "name": "web",
                    "phase": "error",
                    "error": "container not found",
                    "task_status": "not_found"
                }
            ]
        }
    ],
    "missing": ["sbx-missing"]
}

Sandbox Logs

• GET /v1/sandboxes/{id}/logs
• Success: 200 OK
• Failure:
  • 404 Not Found (sandbox does not exist)
  • 413 Payload Too Large (log file or aggregate sandbox logs exceed the read limit)
  • 500 Internal Server Error (log file read I/O failure)

Note:

• Each line is prefixed with the container name, for example [app] ....
• CRI-formatted log lines are sorted by their timestamp across containers.
• If a container log file is not created yet, it is skipped.
• The older GET /v1/sandboxes/{id}/containers/{name}/logs endpoint remains available for per-container compatibility.

Response

{
    "sandbox_id": "sbx-http-demo",
    "logs": {
        "lines": [
            "[app] Serving HTTP on 0.0.0.0 port 8080 (http://0.0.0.0:8080/) ...",
            "[db] database system is ready to accept connections"
        ]
    }
}

Delete Sandbox

• DELETE /v1/sandboxes/{id}
• Success: 200 OK

Response

{
    "id": "sbx-http-demo",
    "phase": "deleted"
}

Manual Reconcile

• POST /v1/reconcile
• Success: 200 OK
• Failure: 500 Internal Server Error

Response

{
    "ok": true
}

Resource Field Format

containers[].resource.cpu

• millicore format: 250m, 500m, 1000m
• core format: 0.25, 0.5, 1, 2

containers[].resource.memory

• Binary units: 128Mi, 1Gi
• Decimal units: 128M, 1G
• Raw bytes as numeric string are also accepted

containers[].resource.ephemeralStorage (optional)

• Total writable storage budget per container.
• sbxlet splits this value into root and tmp limits:
  • / writable layer: 80%
  • /tmp: 20%
• Exceeding each split limit returns ENOSPC.

Common Error Response

{
    "error": "error message"
}

Logging Configuration

• Default config file: /var/lib/sandboxd/sbxlet_config.json
• Logging keys: log_dir, log_file_prefix, app_env
• Compatible environment variable overrides: SANDBOX_LOG_DIR, SANDBOX_LOG_FILE_PREFIX, APP_ENV (supported for backward compatibility, not recommended for new deployments)

Example Create Payload (Wordpress)

{
    "id": "sbx-wordpress-demo",
    "egress": true,
    "ports": [
        {
            "hostPort": 30080,
            "containerPort": 80,
            "protocol": "tcp"
        }
    ],
    "containers": [
        {
            "name": "wordpress",
            "image": "wordpress:6.9.4-php8.3-apache",
            "args": [
                "sh",
                "-c",
                "for i in $(seq 1 90); do php -r '$s=@fsockopen(\"127.0.0.1\",3306,$e,$es,1); if($s){fclose($s); exit(0);} exit(1);' && break; sleep 2; done; exec docker-entrypoint.sh apache2-foreground"
            ],
            "env": [
                "WORDPRESS_DB_HOST=127.0.0.1:3306",
                "WORDPRESS_DB_USER=wordpress",
                "WORDPRESS_DB_PASSWORD=wordpress-pass",
                "WORDPRESS_DB_NAME=wordpress"
            ],
            "workDir": "",
            "resource": {
                "cpu": "200m",
                "memory": "512Mi"
            }
        },
        {
            "name": "mysql",
            "image": "mysql:8.4",
            "args": [],
            "env": [
                "MYSQL_DATABASE=wordpress",
                "MYSQL_USER=wordpress",
                "MYSQL_PASSWORD=wordpress-pass",
                "MYSQL_ROOT_PASSWORD=root-pass"
            ],
            "workDir": "",
            "resource": {
                "cpu": "200m",
                "memory": "768Mi"
            }
        }
    ]
}

This site is open source. Improve this page.