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:

{
  "status": "accepted",
  "action": "pause"
}

Query parameters

Example (from inside the sandbox)

curl -X POST http://127.0.0.1:1029/self/pause
curl -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:

{
  "status": "accepted",
  "action": "delete"
}

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

Example (from inside the sandbox)

curl -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.

# Pause
echo park > /run/self
 
# Delete
echo retire > /run/self

From the SDK

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

import { selfPause, selfDelete } from "@nodeops-createos/sandbox";
 
// Pause this sandbox when the job is done
await selfPause("job-complete");
 
// Or destroy it (irreversible)
await selfDelete();

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