Self-Signal (In-Sandbox)

A workload can pause or delete its own sandbox from the inside, without an API key. This is useful when a job finishes and wants to release its host, or when a long-running process decides it should tear itself down.

At a glance

• Base URL: http://127.0.0.1:1029 (loopback, reachable only from inside the sandbox)
• Auth: none. The endpoint binds to loopback only, so nothing outside the sandbox can reach it. A different sandbox on the network cannot signal yours.
• Methods: POST only. Other methods return 405; unknown paths return 404.

These endpoints are separate from the control-plane pause/resume API, which runs against api.sb.createos.sh and requires an API key. The self-signal endpoints act on whichever sandbox the caller is running inside; there is no id to pass.

POST /self/pause

Pause the current sandbox. The sandbox transitions running → paused, snapshotting disk and memory the same way a control-plane pause does.

Returns 202 Accepted:

JSON
Copy
1{
2  "status": "accepted",
3  "action": "pause"
4}

Query parameters

Example (from inside the sandbox)

Bash
Copy
1curl -X POST http://127.0.0.1:1029/self/pause
2curl -X POST "http://127.0.0.1:1029/self/pause?reason=job-complete"

Resume the sandbox later with the control-plane POST /v1/sandboxes/{id}/resume or createos sandbox resume.

POST /self/delete

Destroy the current sandbox. The sandbox transitions to destroyed. This is irreversible. The sandbox and its state are gone.

Returns 202 Accepted:

JSON
Copy
1{
2  "status": "accepted",
3  "action": "delete"
4}

Accepts the same optional reason query parameter as /self/pause.

Example (from inside the sandbox)

Bash
Copy
1curl -X POST http://127.0.0.1:1029/self/delete

FIFO alternative

For workloads that can't run curl, the agent also exposes a named pipe at /run/self. Write one verb per line:

Lines starting with # are ignored.

Bash
Copy
1# Pause
2echo park > /run/self
3
4# Delete
5echo retire > /run/self

From the SDK

When your code runs inside a sandbox, the TypeScript SDK wraps these endpoints:

TypeScript
Copy
1import { selfPause, selfDelete } from "@nodeops-createos/sandbox";
2
3// Pause this sandbox when the job is done
4await selfPause("job-complete");
5
6// Or destroy it (irreversible)
7await selfDelete();

Both take an optional reason string and resolve once the agent accepts the signal.