Skip to content

Unmount a workspace

Release the writer lease and tear down a mounted workspace. The disposition controls what happens to your local, uncheckpointed writes (spec §11.11, §13.13).

Before you start: hold the mount session id. This is the session field that mount a workspace prints, not the workspace id. The host daemon awcd MUST be running.

  1. Capture the mount session id.

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

    Read the session field from the output. AWC does not list live session ids from the command-line interface (CLI). If you lost the id, you cannot unmount that session.

  2. Choose a disposition for your local writes. Pick one.

    Drop uncheckpointed writes and delete the private upper directory. The spec says destructive discard MUST be explicit when uncheckpointed changes exist (spec §11.11). This is the CLI default.

    Cut a checkpoint from the upper, then unmount. A checkpoint disposition returns both the checkpoint result and the unmount result (spec §13.13).

    Unmount but keep the upper on the host for a bounded recovery window (spec §11.11). Use it when you are not ready to checkpoint or discard.

  3. Unmount the session. Pass the session id and the disposition.

    awcctl workspace unmount sess_01J... --disposition preserve-local

    Omit --disposition to use the default, discard-local. The command prints unmounted sess_01J.... Pass --idempotency-key (or set AWC_IDEMPOTENCY_KEY) so a retry does not double-submit (spec §13.1).

  4. Confirm the lease released and the mount is gone.

    awcctl status

    The mounts field drops by one. Run the unmount a second time on the same session. It returns NOT_FOUND, which proves the session record is gone.

discard-local is destructive

discard-local drops writes you have not checkpointed. The spec requires that destructive discard be explicit when uncheckpointed changes exist (spec §11.11). To keep your writes, use checkpoint or preserve-local. Or run checkpoint a workspace first.

Current build: --disposition is accepted but not honored

The CLI parses --disposition and sends it on the wire, but awcd does not yet act on it. The daemon unmounts the merged view and removes the session record. It releases the writer lease when a control-plane client is configured. It does not:

  • cut a checkpoint for --disposition checkpoint;
  • enforce the explicit-discard gate for --disposition discard-local;
  • delete or retain the upper for --disposition preserve-local.

The full disposition policy is implemented and tested, but it is not wired into the daemon. To save writes today, run checkpoint a workspace before you unmount.

Releasing the lease frees the workspace for another writer

A forced unmount MUST release the writer lease and MUST prevent later publication from that lease generation (spec §11.11, §9.10). The fencing generation keeps a paused or partitioned old host from publishing after a new writer takes over (spec §14.4).

See also