Checkpoints

A checkpoint saves a directory's file state inside one sandbox. Use it before an edit, dependency update or experiment, then restore that directory at its original path if you need to roll back. The sandbox keeps its identity and running processes; memory is not captured or rewound.

When to use which

Before capture or restore

Stop processes and file transfers using the directory, and keep them stopped until the operation completes. Open files, working directories and memory mappings can make the directory busy. Move interactive shells outside the directory too. The API returns 409 when it detects a busy directory, but that check cannot prevent a new writer from opening a file afterward.

Processes are not paused or killed automatically. Checkpoints are file history, not an application-consistent backup of a running database. Restore replaces the directory's current file state, including changes made since the selected checkpoint. Create another checkpoint first if you want to retain those changes. Process memory and files outside the selected directory are unaffected.

The directory must already exist and have an absolute path, such as /workspace/project, /home/user/app, /root/project, /opt/app, /tmp/project or /var/tmp/project.

Unsupported selections include:

• /, entire /tmp or /var/tmp, system trees (/bin, /sbin, /lib, /lib32, /lib64, /libx32, /usr, /etc, /boot, /dev, /proc, /sys, /run, /lost+found), platform filesystem trees (/.fc-overlay, /overlay, /lower, /merged, /oldroot), and container storage (/var/lib/docker, /var/lib/containerd, /var/lib/rancher). Their descendants and directories containing those protected trees are also rejected.
• A symlink anywhere in the selected root path; directories on separate mounts, including attached S3 disks or bind mounts; and directories containing nested mounts.
• A parent or child of another checkpoint-managed directory. Taking another checkpoint of the exact same directory is supported.
• Directories containing hardlinked files or special files such as sockets, devices or named pipes.

Symlinks inside an eligible directory are preserved as links; their targets are not captured. After first capture, the directory becomes a managed mount root. Renaming or removing that root is unsupported, even after deleting all its checkpoint records.

Authentication and responses

Base URL: https://api.sb.createos.sh. Send the account owner's API key or a sandbox access token scoped to this exact sandbox in X-Api-Key. A token for another sandbox cannot access its checkpoints, even when both sandboxes belong to the same account.

All four operations require a running sandbox. They return 200 OK on success with a JSend envelope; there is no asynchronous capture job to poll. Query parameters are rejected, including pagination and path filters. Only create accepts a request body.

POST /v1/sandboxes/{id}/checkpoints

Capture the directory's current file state.

Unknown fields are rejected. The JSON body must contain one object and be no larger than 16 KiB. Parentage is determined from the directory's current history; there is no caller-supplied parent_id.

# Stop processes and file transfers using /workspace/project before this call.
curl -X POST "https://api.sb.createos.sh/v1/sandboxes/$SANDBOX_ID/checkpoints" \
  -H "X-Api-Key: $CREATEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/workspace/project","name":"before-update"}'

Example response:

{
  "status": "success",
  "data": {
    "id": "cp_AAECAwQFBgcICQoLDA0ODw",
    "path": "/workspace/project",
    "name": "before-update",
    "created_at": "2026-11-05T10:00:00Z"
  }
}

Save the returned data.id as CHECKPOINT_ID. Checkpoint IDs are opaque cp_ identifiers; restore and delete accept IDs, not display names. Later checkpoints may include parent_id, identifying the checkpoint from which their directory history continues.

GET /v1/sandboxes/{id}/checkpoints

curl "https://api.sb.createos.sh/v1/sandboxes/$SANDBOX_ID/checkpoints" \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Returns checkpoints for all managed directories in that sandbox, oldest first. data is a plain array of records with the same fields as create, or [] when none exist. It is not the paginated data.data[] envelope used by account-level lists. There is no separate get-by-ID endpoint; find the record in this list.

POST /v1/sandboxes/{id}/checkpoints/{checkpoint}/restore

Restore the selected checkpoint at its original path in the same sandbox. Stop processes and transfers using the directory first. Send no request body; restoring to a different path or another sandbox is not supported.

curl -X POST "https://api.sb.createos.sh/v1/sandboxes/$SANDBOX_ID/checkpoints/$CHECKPOINT_ID/restore" \
  -H "X-Api-Key: $CREATEOS_API_KEY"

{
  "status": "success",
  "data": {
    "checkpoint_id": "cp_AAECAwQFBgcICQoLDA0ODw",
    "path": "/workspace/project"
  }
}

Restoring an older checkpoint does not delete later saved checkpoints. For example, after creating A, B and C, restoring B and creating D gives D a parent_id of B; C remains available. Changes made after B that were never saved in another checkpoint are discarded from the live directory when B is restored.

DELETE /v1/sandboxes/{id}/checkpoints/{checkpoint}

curl -X DELETE "https://api.sb.createos.sh/v1/sandboxes/$SANDBOX_ID/checkpoints/$CHECKPOINT_ID" \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Send no body. Success is {"status":"success","data":{}}.

Deletion removes the checkpoint record without changing the live directory. Other checkpoints remain restorable, even when their parent_id refers to the deleted record. Storage layers still used by another checkpoint or the live directory are retained. Deleting a checkpoint therefore may not immediately free disk space or shorten the active layer chain. Deleting all records does not undo directory enrollment. Destroying the sandbox removes its checkpoint data along with the sandbox disk.

Limits and storage

Storage uses file-level copy-on-write: changing one byte of an existing file can require a copy of the entire file. Allow disk headroom for large-file edits. A checkpoint is not an independent sandbox image and cannot be passed as snapshot_id to sandbox creation.

Pause/resume retains the guest's checkpoint state and mounts; cold-boot recovery reconstructs directory mounts from saved metadata. The upstream rollout notes still require canary validation of pause/resume, full/disk snapshot restore and migration. Do not treat those combinations as production-validated based only on this API reference.

Errors

Use createos sandbox checkpoint for the CLI equivalents. Checkpoint support in a client does not imply the server environment has been rolled out.