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.nodeops.network/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

Parameter	Type	Default	Description
`limit`	integer	50	Max items to return (maximum 500).
`offset`	integer	0	Pagination offset.

Example

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

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "data": [
5      {
6        "id": "net-01k2x…",
7        "name": "backend",
8        "created_at": "2024-01-15T10:00:00Z",
9        "member_count": 2
10      }
11    ],
12    "pagination": {
13      "total": 1,
14      "limit": 50,
15      "offset": 0,
16      "count": 1
17    }
18  }
19}

Notable errors: 401 — missing or invalid API key.

POST `/v1/networks`

Create a new private network.

Auth required: Yes

Request body

Field	Type	Required	Description
`name`	string	Yes	User-facing network name, scoped per user. Example: `backend`.

Example

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

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "id": "net-01k2x…",
5    "name": "backend",
6    "created_at": "2024-01-15T10:00:00Z",
7    "member_count": 0
8  }
9}

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

Parameter	Description
`id`	Network name (e.g. `backend`) or `net-<ulid>` id.

Example

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

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "id": "net-01k2x…",
5    "name": "backend",
6    "created_at": "2024-01-15T10:00:00Z",
7    "member_count": 2,
8    "members": [
9      {
10        "sandbox_id": "sb_01K…",
11        "name": "brave-otter",
12        "status": "running",
13        "ip": "10.42.0.5"
14      },
15      {
16        "sandbox_id": "sb_01L…",
17        "name": "clever-fox",
18        "status": "running",
19        "ip": "10.42.0.6"
20      }
21    ]
22  }
23}

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

Parameter	Description
`id`	Network name or `net-<ulid>` id.

Example

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

Success response 200

JSON
1{
2  "status": "success",
3  "data": { "ok": true }
4}

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

Parameter	Description
`id`	Sandbox id.

Request body

Field	Type	Required	Description
`id`	string	Yes	Network name or `net-<ulid>` id to attach to.

Example

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

Success response 200

JSON
1{
2  "status": "success",
3  "data": { "ok": true }
4}

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

Parameter	Description
`id`	Sandbox id.
`net`	Network name or `net-<ulid>` id.

Example

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

Success response 200

JSON
1{
2  "status": "success",
3  "data": { "ok": true }
4}

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.

100,000+ Builders. One Workspace.