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

Example

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

Success response 200

JSON
Copy
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

Example

Bash
Copy
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
Copy
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

Example

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

Success response 200

JSON
Copy
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

Example

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

Success response 200

JSON
Copy
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

Request body

Example

Bash
Copy
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
Copy
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

Example

Bash
Copy
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
Copy
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.