Skip to content

Checkpoint a workspace

Publish the writes of a mounted workspace as a new immutable snapshot. A checkpoint freezes writes, scans the OverlayFS upper delta, uploads new objects, and atomically advances the workspace head.

The new snapshot is durable only after the control plane publishes the new head in one transaction. Until then, local writes are not remotely durable.

Before you start: the workspace MUST be mounted read-write. You MUST hold the mount session id (the session field from awcctl workspace mount), not the workspace id. The checkpoint reaches the local host daemon over its Unix socket (--host-socket, default /run/awcd/awcd.sock). Set --control-endpoint (or AWC_CONTROL_ENDPOINT) for the status check in step 5.

  1. Capture the mount session id.

    awcctl workspace mount ws_01J... --target /workspace

    Read the session field from the output. awcctl workspace checkpoint takes this session id, not the workspace id.

  2. Choose a checkpoint mode. Pick one.

    The only mode advertised as application-consistent. The daemon freezes the mount's execution cgroup, runs syncfs, scans a stable delta, publishes, then resumes the writer.

    The cgroup MUST be sealed into the mount ticket at mount time. A mount that has no cgroup is rejected (see the candid note below) with:

    quiesced checkpoint requires a ticket-sealed execution cgroup

    Use when the integration cannot be frozen. You assert that all writes have stopped before you run the command. The daemon skips the freeze but still runs syncfs. The result is consistent only if your assertion is true. The mode is recorded in provenance, and a cooperative checkpoint MUST NOT be labeled quiesced.

  3. Run the checkpoint. Pass the session id, the mode, and a message.

    awcctl workspace checkpoint sess_01J... \
  --mode cooperative \
  --message "retry-investigation-17 step 3" \
  --label agent_run=run_991 \
  --idempotency-key cp-run991-3

    The call goes to the local host daemon, which drives the full validate, quiesce, construct, upload, publish, and cleanup pipeline.

  4. Capture the new snapshot id and version. The result prints the snapshot, digest, and version fields.

    snapshot      snap_01J...
digest        sha256:...
version       4

    Add --output json to capture the id in a script. The snapshot is durable only once this result returns.

  5. Confirm the workspace head advanced. Run status against the workspace id.

    awcctl workspace status ws_01J...

    The head field now equals the new snapshot id and version incremented by one. If head did not change, the publish was rejected. The workspace head references only the complete prior or the complete new snapshot.

Idempotency key is required

The host daemon rejects a checkpoint that has an empty idempotency key. Pass --idempotency-key, or set AWC_IDEMPOTENCY_KEY. A retry with the same key returns the already-published snapshot instead of duplicating work.

Current build: CLI mounts have no cgroup

awcctl workspace mount issues a ticket with execution_cgroup unset. A quiesced checkpoint (the default) on a CLI-mounted workspace then fails with the string above. An integration that runs the writer under a managed cgroup seals that cgroup into the ticket at mount time. The local-development smoke therefore runs --mode cooperative (the local-dev smoke).

See also