Bandwidth & Resize
Each sandbox starts with a deployment-configured bandwidth allowance; the software default is 5 GiB. Read /bandwidth for the actual quota. When the quota is exhausted, outbound traffic stops until you top up. Disk can be grown online (no restart) to any of the fixed available sizes.
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": 5368709120,
"used_bytes": 1073741824,
"remaining_bytes": 4294967296,
"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": 16106127360,
"used_bytes": 5368709120,
"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.
POST /v1/sandboxes/{id}/resize
Grow a sandbox's disk online. No sandbox restart is needed, though the resize may take a few seconds on large changes.
Disk size can only increase, not decrease. The new size must be one of the fixed menu values.
Auth required: Yes
Path parameters
| Parameter | Description |
|---|---|
id | Sandbox id. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
disk_mib | integer | Yes | New disk size in MiB. Must be one of: 10240, 20480, 30720, 40960, 51200, 61440. Must be larger than the current size. |
Example: grow to 20 GiB
curl -X POST https://api.sb.createos.sh/v1/sandboxes/sb-01K.../resize \
-H "X-Api-Key: $CREATEOS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"disk_mib": 20480}'Success response 200
{
"status": "success",
"data": {
"id": "sb-01K…",
"disk_mib": 20480
}
}Notable errors: 400 invalid disk_mib (not in the allowed list, or smaller than current size). 404 sandbox not found.