CLI Reference: Workspace
Commands for managing overlay filesystem snapshots per agent.
Each agent has an overlay filesystem workspace. Snapshots capture the current state of the overlay so it can be reviewed or rolled back. See Workspace Snapshots for background.
ash workspace snapshot
Force an immediate snapshot of an agent's current workspace state.
ash workspace snapshot <agent-id>
Captures the current overlay layer as a named snapshot. Returns the snapshot index.
ash workspace history
List all available snapshots for an agent.
ash workspace history <agent-id>
Output per snapshot:
| Field | Description |
|---|---|
index | Snapshot number (0 = oldest) |
created_at | RFC3339 timestamp |
description | Auto-generated or operator-provided label |
ash workspace diff
Show files changed in the current overlay versus the last snapshot.
ash workspace diff <agent-id>
Displays a list of added, modified, and deleted files relative to the most recent snapshot.
ash workspace rollback
Roll back an agent's workspace to a previous snapshot.
ash workspace rollback <agent-id> <index>
| Argument | Description |
|---|---|
agent-id | Target agent |
index | Snapshot index to restore (from ash workspace history) |
The current overlay state is discarded and replaced with the contents of the specified snapshot. The agent must be in a quiescent state (not mid-action) for rollback to proceed safely.
ash workspace commit
Promote the current overlay to a permanent snapshot and clear the upper layer.
ash workspace commit <agent-id>
This is a "checkpoint" operation: the current working state is saved as a new immutable snapshot and the mutable overlay layer is reset. Useful before a risky sequence of operations.