Networks

Private networks let sandboxes talk to each other by name. Every sandbox that joins the same network is reachable at its name (e.g. brave-otter) from any peer in that network. Networks are fully isolated from each other and from the public internet. Sandbox-to-sandbox traffic stays on the overlay and is blocked at the host layer for VMs in different networks.

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/networks

List all networks owned by the caller.

Auth required: Yes

Query parameters

Example

curl https://api.sb.createos.sh/v1/networks \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Success response 200

{
  "status": "success",
  "data": {
    "data": [
      {
        "id": "net-01k2x…",
        "name": "backend",
        "created_at": "2024-01-15T10:00:00Z",
        "member_count": 2
      }
    ],
    "pagination": {
      "total": 1,
      "limit": 50,
      "offset": 0,
      "count": 1
    }
  }
}

Notable errors: 401 missing or invalid API key.

POST /v1/networks

Create a new private network.

Auth required: Yes

Request body

Example

curl -X POST https://api.sb.createos.sh/v1/networks \
  -H "X-Api-Key: $CREATEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "backend"}'

Success response 200

{
  "status": "success",
  "data": {
    "id": "net-01k2x…",
    "name": "backend",
    "created_at": "2024-01-15T10:00:00Z",
    "member_count": 0
  }
}

Notable errors: 400 validation failure (e.g. duplicate name). 401 unauthorized.

GET /v1/networks/{id}

Get details for one network, including its current member list with per-member IPs.

Auth required: Yes

Path parameters

Example

curl https://api.sb.createos.sh/v1/networks/backend \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Success response 200

{
  "status": "success",
  "data": {
    "id": "net-01k2x…",
    "name": "backend",
    "created_at": "2024-01-15T10:00:00Z",
    "member_count": 2,
    "members": [
      {
        "sandbox_id": "sb-01K…",
        "name": "brave-otter",
        "status": "running",
        "ip": "10.42.0.5"
      },
      {
        "sandbox_id": "sb-01L…",
        "name": "clever-fox",
        "status": "running",
        "ip": "10.42.0.6"
      }
    ]
  }
}

Notable errors: 401 unauthorized. 404 network not found.

DELETE /v1/networks/{id}

Delete a network. The network must have no members; detach all sandboxes first.

Auth required: Yes

Path parameters

Example

curl -X DELETE https://api.sb.createos.sh/v1/networks/backend \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Success response 200

{
  "status": "success",
  "data": { "ok": true }
}

Notable errors: 401 unauthorized. 404 not found. 409 network still has active members; detach all sandboxes first.

POST /v1/sandboxes/{id}/networks

Attach a running sandbox to a network. After attachment the sandbox is reachable by its name from other network members.

Auth required: Yes

Path parameters

Request body

Example

curl -X POST https://api.sb.createos.sh/v1/sandboxes/sb-01K.../networks \
  -H "X-Api-Key: $CREATEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "backend"}'

Success response 200

{
  "status": "success",
  "data": { "ok": true }
}

Notable errors: 400 validation error. 401 unauthorized. 404 sandbox or network not found.

DELETE /v1/sandboxes/{id}/networks/{net}

Detach a sandbox from a network.

Auth required: Yes

Path parameters

Example

curl -X DELETE https://api.sb.createos.sh/v1/sandboxes/sb-01K.../networks/backend \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Success response 200

{
  "status": "success",
  "data": { "ok": true }
}

Notable errors: 401 unauthorized. 404 sandbox or membership not found.

Name-based reachability

Inside a network, each member sandbox is reachable by its user-facing name (the same name you gave it at create time, e.g. brave-otter). You can curl http://brave-otter:8080 from any peer in the same network without knowing the IP.

Networks are isolated: sandboxes in different networks cannot reach each other, and neither can sandboxes with no network at all.

You can attach a sandbox to a network at create time by passing networks: [{"id": "backend"}] in the POST /v1/sandboxes body, or at any time after creation via POST /v1/sandboxes/{id}/networks.

Related

• Product explanation and cluster examples: Sandbox networking.
• Egress governs traffic leaving the sandbox; private networks are separate from it.
• Per-plan network caps: Limits & defaults.