Mount a workspace¶

Mount a workspace as a writable directory on a host. The mount runs behind a signed, replay-protected ticket that the control plane issues and the host daemon awcd redeems (spec §13.8, §13.9).

Before you start: get a workspace id from fork a workspace. Confirm the target path is under the host allow-list, which is the configured workspace_root plus allowed_bind_roots. awcd MUST be running with its socket present at /run/awcd/awcd.sock. Set --control-endpoint (or AWC_CONTROL_ENDPOINT) and a bearer --token (or AWC_TOKEN) for the control plane.

Confirm the workspace and target.
```
awcctl workspace status ws_01J...
```
The target MUST be an absolute path under an allow-listed root. awcd rejects relative paths, .. or . segments, sibling prefixes, and any path outside the roots (spec §13.9). It MUST NOT accept an arbitrary host path from an untrusted caller.
Mount the workspace read-write.
```
awcctl workspace mount ws_01J... --target /var/lib/awc/workspaces/run-991
```
The CLI learns the host id, issues a signed ticket over the control plane, then redeems it at awcd. For a read-write mount the control plane acquires an exclusive writer lease first (spec §5.4, §13.8). At most one unexpired writer lease may exist per workspace (spec §6.6).

Capture the mount session id.

session    ms_01J...
target     /var/lib/awc/workspaces/run-991
merged     /var/lib/awc/workspaces/ws_01J.../3/merged
root       sha256:...
lease gen  3

Save the session value. You pass it to checkpoint and unmount.

Confirm the kernel mounted OverlayFS.
```
findmnt -n -o FSTYPE --target /var/lib/awc/workspaces/run-991
```
The command prints overlay. awcd builds a merged OverlayFS view and bind-mounts it into your target, so the target carries the overlay type (spec §5.4).
For a read-only mount, add --read-only.
```
awcctl workspace mount ws_01J... \
  --target /var/lib/awc/workspaces/review \
  --read-only
```
A read-only mount MAY be created without an exclusive writer lease (spec §5.4, §13.8). --target is required either way.
To release the mount later, see unmount a workspace.

Namespace bind targets are not wired

The spec lets awcd bind the merged view into an authorized sandbox mount namespace or a configured host target (spec §15.4). The current build supports the host-target path only. A request that carries a namespace target returns UNIMPLEMENTED.