Bandwidth & Disk Sizing
Each sandbox starts with a deployment-configured bandwidth allowance; the software default is 50 GiB. Read /bandwidth for the actual quota. When the quota is exhausted, outbound traffic stops until you top up. Choose root disk size at creation; live disk resizing is no longer supported.
Get your API key from https://createos.sh/app/profile. Pass it as X-Api-Key: <token> on every request.
Base URL: https://api.sb.createos.sh
At a glance
- Base URL:
https://api.sb.createos.sh - Auth:
X-Api-Key: <token>header. Get a token - Response envelope: JSend,
{"status": "...", "data": ...}
GET /v1/sandboxes/{id}/bandwidth
Read the current bandwidth quota and usage for a sandbox.
Auth required: Yes
Path parameters
| Parameter | Description |
|---|---|
id | Sandbox id. |
Example
curl https://api.sb.createos.sh/v1/sandboxes/sb-01K.../bandwidth \
-H "X-Api-Key: $CREATEOS_API_KEY"Success response 200
{
"status": "success",
"data": {
"id": "sb-01K…",
"quota_bytes": 53687091200,
"used_bytes": 1073741824,
"remaining_bytes": 52613349376,
"capped": false
}
}Response fields
| Field | Type | Description |
|---|---|---|
id | string | Sandbox id. |
quota_bytes | integer | Total outbound bandwidth budget in bytes. |
used_bytes | integer | Cumulative outbound bytes consumed by the sandbox, including across pause/resume. Recharge does not reset this counter. |
ingress_bytes | integer | Inbound bytes for observation; these do not consume the outbound quota. |
remaining_bytes | integer | quota_bytes - used_bytes. |
capped | boolean | true when outbound traffic is currently being dropped in-kernel because usage hit the quota. Clears within ~5 seconds of a successful recharge. |
Notable errors: 404 sandbox not found.
POST /v1/sandboxes/{id}/bandwidth/recharge
Top up a sandbox's bandwidth quota by adding bytes to the current quota. This is an additive operation; it adds to the existing quota rather than replacing it.
If the sandbox is currently capped (capped: true), the in-kernel DROP rule is removed within ~5 seconds after a recharge that pushes usage below the new quota.
Auth required: Yes
Path parameters
| Parameter | Description |
|---|---|
id | Sandbox id. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
add_bytes | integer | Yes | Positive number of bytes to add, at most 100 GiB (107374182400) per call. Adds to the quota without resetting usage. |
Example: add 10 GiB
curl -X POST https://api.sb.createos.sh/v1/sandboxes/sb-01K.../bandwidth/recharge \
-H "X-Api-Key: $CREATEOS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"add_bytes": 10737418240}'Success response 200
{
"status": "success",
"data": {
"id": "sb-01K…",
"quota_bytes": 64424509440,
"used_bytes": 53687091200,
"remaining_bytes": 10737418240,
"capped": false
}
}The sandbox must be running. Recharge consumes account credit; check your balance before requesting a top-up.
Notable errors: 400 invalid add_bytes, 402 insufficient credit, 404 sandbox not found, 409 sandbox is not running, 502 billing service unavailable.
Disk sizing
The former POST /v1/sandboxes/{id}/resize endpoint has been removed. Select disk_mib when creating a sandbox: 10240, 20480, 30720, 40960, 51200 or 61440 MiB, subject to your plan.
To preserve a root filesystem in a larger sandbox, capture a disk snapshot and restore it into a new sandbox with a larger allowed disk_mib. This creates a new identity; it does not resize the source. Full snapshots require the captured disk size.