--- title: Control full: true _openapi: preload: - ./specs/toolbox-api.json toc: - depth: 2 title: Report whether caller-started processes are running url: '#report-whether-caller-started-processes-are-running' - depth: 2 title: Release the entrypoint gate url: '#release-the-entrypoint-gate' - depth: 2 title: Freeze the scratch filesystem for a disk snapshot url: '#freeze-the-scratch-filesystem-for-a-disk-snapshot' - depth: 2 title: Thaw the scratch filesystem url: '#thaw-the-scratch-filesystem' - depth: 2 title: List bucket mounts url: '#list-bucket-mounts' - depth: 2 title: Apply bucket mounts url: '#apply-bucket-mounts' - depth: 2 title: Unmount one bucket mount url: '#unmount-one-bucket-mount' - depth: 2 title: Discover `/rlp/secrets` capabilities url: '#discover-rlpsecrets-capabilities' - depth: 2 title: Inject and retract placeholder env vars, plus an optional CA url: '#inject-and-retract-placeholder-env-vars-plus-an-optional-ca' - depth: 2 title: Arm process-bound self deletion url: '#arm-process-bound-self-deletion' - depth: 2 title: Set or rotate the control bearer token url: '#set-or-rotate-the-control-bearer-token' - depth: 2 title: Set the sandbox default OS user url: '#set-the-sandbox-default-os-user' - depth: 2 title: POST /rlp/volume-apply/apply url: '#post-rlpvolume-applyapply' - depth: 2 title: POST /rlp/volume-apply/begin url: '#post-rlpvolume-applybegin' - depth: 2 title: POST /rlp/volume-apply/capture url: '#post-rlpvolume-applycapture' - depth: 2 title: POST /rlp/volume-apply/confirm url: '#post-rlpvolume-applyconfirm' - depth: 2 title: POST /rlp/volume-apply/reserve url: '#post-rlpvolume-applyreserve' - depth: 2 title: POST /rlp/volume-apply/stage url: '#post-rlpvolume-applystage' - depth: 2 title: GET /rlp/volume-apply/status url: '#get-rlpvolume-applystatus' - depth: 2 title: Register internal volume-sync bindings url: '#register-internal-volume-sync-bindings' - depth: 2 title: Poll internal volume-sync requests url: '#poll-internal-volume-sync-requests' - depth: 2 title: Complete an internal volume-sync delivery url: '#complete-an-internal-volume-sync-delivery' structuredData: headings: - content: Report whether caller-started processes are running id: report-whether-caller-started-processes-are-running - content: Release the entrypoint gate id: release-the-entrypoint-gate - content: Freeze the scratch filesystem for a disk snapshot id: freeze-the-scratch-filesystem-for-a-disk-snapshot - content: Thaw the scratch filesystem id: thaw-the-scratch-filesystem - content: List bucket mounts id: list-bucket-mounts - content: Apply bucket mounts id: apply-bucket-mounts - content: Unmount one bucket mount id: unmount-one-bucket-mount - content: Discover `/rlp/secrets` capabilities id: discover-rlpsecrets-capabilities - content: Inject and retract placeholder env vars, plus an optional CA id: inject-and-retract-placeholder-env-vars-plus-an-optional-ca - content: Arm process-bound self deletion id: arm-process-bound-self-deletion - content: Set or rotate the control bearer token id: set-or-rotate-the-control-bearer-token - content: Set the sandbox default OS user id: set-the-sandbox-default-os-user - content: POST /rlp/volume-apply/apply id: post-rlpvolume-applyapply - content: POST /rlp/volume-apply/begin id: post-rlpvolume-applybegin - content: POST /rlp/volume-apply/capture id: post-rlpvolume-applycapture - content: POST /rlp/volume-apply/confirm id: post-rlpvolume-applyconfirm - content: POST /rlp/volume-apply/reserve id: post-rlpvolume-applyreserve - content: POST /rlp/volume-apply/stage id: post-rlpvolume-applystage - content: GET /rlp/volume-apply/status id: get-rlpvolume-applystatus - content: Register internal volume-sync bindings id: register-internal-volume-sync-bindings - content: Poll internal volume-sync requests id: poll-internal-volume-sync-requests - content: Complete an internal volume-sync delivery id: complete-an-internal-volume-sync-delivery contents: - content: "Counts the daemon's non-terminal processes that hold the sandbox idle clock (PLAN-DAEMON-PROCESS-ACTIVITY): every non-PTY process a caller started — a standalone `kind=exec` process, a session member, or a `kind=code` cell, including a cell still queued in `starting`. PTYs, session shells, language kernels and system processes (the entrypoint, `dockerd`) never count, and neither do records reconciled `lost` at boot. The runner polls this route and keeps the sandbox from auto-stopping while `busy` is `true`. Read-only and immediate; it never waits." heading: report-whether-caller-started-processes-are-running - content: 'Releases the runner-held entrypoint gate. Once released, the Linux daemon runs its one-per-boot startup coordinator: Docker Engine startup (reported on `GET /docker/status`), then the image entrypoint. `fnReady=1` marks the release of a function-ready template build, which skips Docker startup (status `deferred`) but still starts the entrypoint. Idempotent — repeat calls answer 200 without spawning a second entrypoint. A platform without an image entrypoint (Windows) answers 200 as a no-op.' heading: release-the-entrypoint-gate - content: "Issues `FIFREEZE` on the guest's scratch ext4 filesystem — the mount whose mountinfo root is `/runtime/containerd` (or `/runtime/docker`), bind-mounted by guest init — which checkpoints the journal and blocks new writers, so the runner's host-side trim can trust the captured copy's block bitmaps. The runner freezes right before pausing the VM and thaws after resume. An auto-thaw fires `timeoutMs` (default 10000, clamped to 1000..=30000) after the request arrives, so a lost thaw cannot wedge the guest. Idempotent: a repeat call while frozen re-arms the auto-thaw and answers 200. While frozen, other requests that write to that filesystem block until the thaw." heading: freeze-the-scratch-filesystem-for-a-disk-snapshot - content: 'Issues `FITHAW` on the filesystem `POST /rlp/fs-freeze` froze and cancels its auto-thaw. Idempotent: nothing frozen, or a filesystem already thawed, answers 200. Windows sandboxes answer 200 as a no-op.' heading: thaw-the-scratch-filesystem - content: Returns the daemon's redacted bucket mount state. Credentials never appear in this response. heading: list-bucket-mounts - content: Applies the desired bucket mount set. Gateway credentials are write-only and never echoed back. heading: apply-bucket-mounts - content: Unmounts one bucket mount by absolute path. The legacy `name` alias is still accepted for runner compatibility. heading: unmount-one-bucket-mount - content: 'Returns the control-surface features this daemon exposes for secrets delivery. Old daemon generations answer the plain-text `405 method not allowed` fallback here, which is how a runner can distinguish a POST-only `/rlp/secrets` from one that also supports compare-and-remove overlay retracts. `compare_remove` is per implementation: a daemon that answers `false` still accepts env and CA pushes, but refuses a non-empty `remove` with `400 BAD_REQUEST`.' heading: discover-rlpsecrets-capabilities - content: "Pushes placeholder environment variables plus an optional PEM CA bundle fragment before the runner releases the entrypoint gate, and may retract previously pushed names from future spawns through compare-and-remove `remove` entries when `GET /rlp/secrets` reports `compare_remove: true`. Implementations that report `false` reject a non-empty `remove` with `400 BAD_REQUEST`. Reserved keys are refused with 400 naming the key, and nothing from that request is stored: keys starting with `RLP_`, any `DAYTONA_*` key other than `DAYTONA_SANDBOX_TOKEN`, `DAYTONA_API_URL`, `DAYTONA_OTEL_ENDPOINT`, `DAYTONA_DOCKER_START`, `DAYTONA_FN_PORT` and `DAYTONA_FN_HANDLER` (the last two are platform-injected by the API's functions service for the tenant's handler process), and keys that are not valid variable names (empty, or containing `=`, NUL, CR or LF). The sandbox's create env travels on this route too, so `PATH`, `LD_*` and the CA-bundle variables (`SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `NODE_EXTRA_CA_CERTS`, `GIT_SSL_CAINFO`, `DENO_CERT`) are admitted; once an egress CA is installed, the daemon's own bundle paths replace any pushed value under the CA names. No size limit applies here: the API bounds the create env, and the tenant `POST /env` caps do not apply." heading: inject-and-retract-placeholder-env-vars-plus-an-optional-ca - content: Arms one process-bound lifecycle action (`delete`, `stop`, or `pause`) for this sandbox. heading: arm-process-bound-self-deletion - content: "The runner's first control call on every boot path (PLAN-DAEMON-LISTENER-HARDENING). Accepted without a bearer only while the daemon holds no token (bootstrap); once a token is set, the request must carry it as `Authorization: Bearer …` and the body's token replaces it (rotation — a clone resumed from a template rotates the template's token to a per-clone one). Re-pushing the token the daemon already holds is a 200 no-op, so a retry after a lost 200 is idempotent. The token lives in daemon memory only and is never echoed, logged or exported. Like every control route this one sits behind the gateway-peer guard (403); unlike the others it bypasses the bearer layer and checks the bearer itself (401). A daemon that predates control tokens answers the plain-text `404 page not found` fallback." heading: set-or-rotate-the-control-bearer-token - content: 'Sets the OS user every later exec, session, SSH login and git operation runs as, creating the account inside the guest if the image lacks it (issue #167). Pushed by the runner before the entrypoint gate releases. One-shot per boot: re-pushing the same name is an idempotent no-op; a different name is refused.' heading: set-the-sandbox-default-os-user - content: "Protocol 1 runner-only correlation state, not a credential or proof of ownership. The first session is sealed for the daemon's lifetime: a different session is refused with 409; repeating the session requires identical bindings." heading: register-internal-volume-sync-bindings - content: Returns the oldest outstanding delivery without removing it. Waits at most 30000 ms. A missing request is null, not proof of execution failure. heading: poll-internal-volume-sync-requests - content: Requires the submitted session, request, volume, generation, operation and delivery id. Identical completions replay; contradictory results refuse. Pending, unavailable and rate_limited finish this delivery but allow internal resubmission with the same effect identity and a new delivery id. Rate admission is enforced by the runner across reconnects. heading: complete-an-internal-volume-sync-delivery methods: - GET - POST - POST - POST - GET - POST - DELETE - GET - POST - POST - POST - POST - POST - POST - POST - POST - POST - POST - GET - POST - GET - POST --- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} export default function Layout(props) { const { OpenAPIPage } = props.components ?? {}; return ( <> {props.children} ); }