Skip to content

Fork a workspace

Create one or many private, metadata-only workspaces from a snapshot. A fork writes workspace metadata only. It MUST NOT copy content objects (spec §5.3), so the cost is independent of the snapshot size (spec §20.2, gate 1).

Before you start: the source snapshot MUST be in the READY state (spec §5.3, §6.4). Get its id from awcctl snapshot list or awcctl snapshot create. Set --tenant (or AWC_TENANT) and --project (or AWC_PROJECT).

  1. Confirm the source is ready.

    awcctl snapshot inspect snap_01J...

    A not-ready snapshot returns SNAPSHOT_NOT_READY. Fork the ready id only.

  2. Fork. Pick one mode.

    Fork one workspace from a snapshot. This calls POST /v1/workspaces (spec §13.6).

    awcctl workspace fork \
  --snapshot snap_01J... \
  --ttl 2h \
  --name retry-investigation-17 \
  --label agent_run=run_991

    --snapshot forks exactly one workspace. Pass --count only with --workspace.

    Fork many workspaces from an existing workspace's base, head, or a specific snapshot. This calls POST /v1/workspaces/{workspace_id}:fork (spec §13.7).

    awcctl workspace fork \
  --workspace ws_01J... \
  --from base \
  --count 10 \
  --name candidate \
  --ttl 2h

    --from accepts base, head (the default), or a snapshot id. The server caps a batch at 1000 workspaces (MAX_FORK_BATCH). For larger fan-out, repeat the call with a new --idempotency-key.

  3. Capture the workspace id. The new workspace starts in the IDLE state with version = 1 and base == head.

    • Single fork prints the workspace fields, including id, state, base, head, and expires.
    • Batch fork prints one line per workspace as id<TAB>state.

    Add --output json to capture ids in a script.

  4. (Optional) Inspect a workspace.

    awcctl workspace status ws_01J...

--ttl is required

--ttl sets the workspace lifetime. It accepts 2h, 30m, 3600s, a bare number of seconds, or 1d. The workspace expires after this duration.

Idempotent by default

Every fork honors --idempotency-key (spec §13.1). Repeat a fork with the same key and the server returns the original result instead of duplicating workspaces.

See also