Use ws-ckpt - Alibaba Cloud Linux - Alibaba Cloud Documentation Center

ws-ckpt is a snapshot tool for AI agent workspaces that provides millisecond-level checkpoint and rollback capabilities.

Using ws-ckpt with Harness Agents

1. Installation

1.1 Check for the ws-ckpt CLI

ws-ckpt --version

If the tool is not installed, use yum to install it.

sudo yum install ws-ckpt

1.2 Install the ws-ckpt plug-in for OpenClaw

Run the following commands to install or uninstall the plug-in:

# Install the plug-in for OpenClaw
ws-ckpt plugin install --runtime openclaw
# Uninstall the plug-in for OpenClaw
ws-ckpt plugin uninstall --runtime openclaw

The default workspace path is ~/.openclaw/workspace. To customize this path, instruct OpenClaw using natural language or modify the ~/.openclaw/ws-ckpt.json configuration file:

"workspace": "/path/to/workspace"

Important

The workspace path must not be the OpenClaw launch directory or any of its parent directories.
Because the snapshot feature modifies the file system and affects the cwd of processes within the workspace, you must not set the workspace path to a critical system directory, such as the home directory or the root directory.

Note: The OpenClaw gateway is typically launched from the home directory, and the TUI is launched from the directory in which the TUI command is run.

To enable automatic snapshots, instruct OpenClaw using natural language or modify the ~/.openclaw/ws-ckpt.json configuration file after installation. The plug-in will then create a snapshot at the end of each conversation round:

"autoCheckpoint": true

1.3 Install the ws-ckpt plug-in for Hermes

Run the following commands to install or uninstall the plug-in:

# Install the plug-in for Hermes
ws-ckpt plugin install --runtime hermes
# Uninstall the plug-in for Hermes
ws-ckpt plugin uninstall --runtime hermes

You must configure the workspace path. After installing the plug-in, run the following command:

# Update the config file to set the workspace
hermes config set plugins.ws-ckpt.workspace /path/to/workspace

Important

The workspace path must not be the Hermes launch directory or any of its parent directories.
Because the snapshot feature modifies the file system and affects the cwd of processes within the workspace, you must not set the workspace path to a critical system directory, such as the home directory or the root directory.

Note: The Hermes gateway is typically launched from ~/.hermes/hermes-agent, and the TUI is launched from the directory in which the TUI command is run.

To enable automatic snapshots, run the following command after the plug-in is installed, or instruct Hermes using natural language. The plug-in then takes an automatic snapshot at the end of each conversation round:

# Update the config file to enable automatic snapshots
hermes config set plugins.ws-ckpt.autoCheckpoint true

1.4 Install the ws-ckpt skill for other agents

Local installation

Skill file path: /usr/share/anolisa/runtime/skills/ws-ckpt/SKILL.md
Instruct the agent: "Install the skill from /usr/share/anolisa/runtime/skills/ws-ckpt/SKILL.md."

Install from GitHub

Skill file GitHub URL: https://github.com/alibaba/anolisa/blob/main/src/ws-ckpt/src/skills/ws-ckpt/SKILL.md
Instruct the agent: "Install the skill from https://github.com/alibaba/anolisa/blob/main/src/ws-ckpt/src/skills/ws-ckpt/SKILL.md."

Note

The plug-in and the skill cannot be installed at the same time; they are mutually exclusive.

The skill carries the risk of being misinterpreted by the model. We recommend that you use the plug-in.

2. Using natural language commands

2.1 Set the workspace directory

# User input
Set the snapshot workspace directory to /path/to/workspace

Important: Persisting OpenClaw configuration changes triggers a gateway restart. Therefore, in-session modifications are made only in memory and apply only to the current session.

2.2 Create a snapshot

# User input
Create a snapshot named test1 with the message "test snapshot"

Important: You must provide a unique name for the snapshot. This name is used to identify the snapshot for subsequent commands.

2.3 Enable automatic snapshots

When enabled, a snapshot is automatically created after each conversation round.

# User input
Enable automatic snapshots for each conversation round

2.4 Enable scheduled snapshots

When enabled, snapshots are automatically created at specified times.

Scheduled jobs use a five-field cron expression to specify minute, hour, day of the month, month, and day of the week. This format supports most recurring and one-time scheduling needs, but does not support second-level precision, event-based triggers (e.g., run after a file change), or chained scheduling (e.g., run B after A completes).

# User input
Schedule a snapshot for 12:00 PM every day

2.5 List snapshots

# User input
List all snapshots

2.6 Roll back a snapshot

# User input
Roll back to snapshot test1

Important: You must specify the snapshot by its name.

2.7 Delete a snapshot

# User input
Delete snapshot test1

Important: You must specify the snapshot by its name.

2.8 Enable automatic snapshot cleanup

# User input
Enable automatic snapshot cleanup and keep only snapshots from the last 7 days

Note

By default, automatic cleanup settings apply only to the current workspace. To apply the cleanup policy to all workspaces on the server, you must explicitly configure global automatic cleanup.

Using the CLI

1. Create a snapshot

ws-ckpt checkpoint -w <workspace> [-s <snapshot id>] [-m <message>] [--metadata <json>]

Parameter	Alias	Required	Description
`--workspace`	`-w`	Yes	The workspace path or ID.
`--snapshot`	`-s`	No	A unique ID for the snapshot. If not specified, one is generated automatically.
`--message`	`-m`	No	A description for the snapshot.
`--metadata`		No	Additional metadata in JSON format.

Examples:

# Basic usage
ws-ckpt checkpoint -w ./my-project -s test

# With a message
ws-ckpt checkpoint -w ./my-project -s test -m "initial state"

# With metadata
ws-ckpt checkpoint -w ws-6d5aaa -s test --metadata '{"tool":"write","file":"main.py"}'

2. Roll back to a specific snapshot

ws-ckpt rollback -w <workspace> {-s <snapshot> | -n <num_ancestors>} [--preview]

The --snapshot parameter (alias -s) accepts a snapshot ID, such as test.

--workspace (alias -w) specifies the workspace path or ID.

Parameter	Alias	Required	Description
`--snapshot`	`-s`	No	The ID of the target snapshot. This parameter is mutually exclusive with `-n`.
`--num-ancestors`	`-n`	No	Rolls back N snapshots along the parent chain. This parameter is mutually exclusive with `-s`.
`--workspace`	`-w`	Yes	The workspace path or ID.
`--preview`		No	Displays a diff between the target snapshot and the current workspace without applying any changes.

Example:

# Roll back to a snapshot by its ID
ws-ckpt rollback -w ./my-project -s test
# Roll back three snapshots
ws-ckpt rollback -w <workspace> -n 3
# Preview the difference between the 'test' snapshot and the current workspace
ws-ckpt rollback -w ./my-project -s test --preview

3. List snapshots

ws-ckpt list [-w <workspace>] [--format <table|json>]

Parameter	Alias	Required	Description
`--workspace`	`-w`	No	Omitting `-w` lists all workspace snapshots.
`--format`		No	The output format. Valid values: table or json.

Examples:

# List snapshots from all workspaces
ws-ckpt list

# List snapshots in a specific workspace
ws-ckpt list -w ./my-project

# Output in JSON format
ws-ckpt list -w workspace-6d5aaa --format json

4. View snapshot differences

ws-ckpt diff -w <workspace> -f <snapshot> [-t <snapshot>]

Parameter	Alias	Required	Description
`--workspace`	`-w`	Yes	The workspace path or ID.
`--from`	`-f`	Yes	The starting snapshot ID.
`--to`	`-t`	No	The target snapshot ID. If omitted, the command compares the 'from' snapshot with the current workspace state.

Examples:

# Compare two snapshots
ws-ckpt diff -w ./my-project -f v1 -t v2

# Compare a snapshot with the current workspace state
ws-ckpt diff -w ./my-project -f v1

5. Delete a snapshot

ws-ckpt delete [-w <workspace>] -s <snapshot> [--force]

Parameter	Alias	Required	Description
`--snapshot`	`-s`	Yes	The ID of the snapshot.
`--workspace`	`-w`	No	The path or ID of the workspace. If the snapshot ID is globally unique, the `-w` parameter is not required. If the ID is duplicated across workspaces, you must specify the workspace.

Examples:

# Delete a single snapshot
ws-ckpt delete -w ./my-project -s test

# Globally delete by snapshot ID (no -w needed if the ID is unique)
ws-ckpt delete -s test

6. Check status

ws-ckpt status [-w <workspace>] [--format <table|json>]

Parameter	Alias	Required	Description
`--workspace`	`-w`	No	Omitting `-w` displays the global status.
`--format`		No	The output format. Valid values: table or json.

Examples:

# Global status
ws-ckpt status

# Status for a specific workspace
ws-ckpt status -w ./my-project

7. Configure automatic snapshot cleanup

ws-ckpt config 
      [-g | -w <workspace>]
      [--enable-auto-cleanup]
      [--disable-auto-cleanup]
      [--auto-cleanup-keep <AUTO_CLEANUP_KEEP>]
      [--auto-cleanup-interval <AUTO_CLEANUP_INTERVAL>]

Parameter	Alias	Required	Description
`--global`	`-g`	No	Specifies that the command applies to the global configuration.
`--workspace`	`-w`	No	Specifies the configuration for a particular workspace.
`--enable-auto-cleanup`		No	Enables automatic snapshot cleanup.
`--disable-auto-cleanup`		No	Disables automatic snapshot cleanup.
`--auto-cleanup-keep`		No	The cleanup retention setting. Specify either an integer (count mode; 0 disables cleanup) or a retention duration such as "30d" (duration mode; valid units are seconds, minutes, hours, days, and weeks).
`--auto-cleanup-interval`		No	The automatic cleanup interval, in seconds. A value of 0 disables the scheduling loop.

Note

Cleanup can be configured globally or for individual workspaces. Workspace-specific settings override global settings.

Examples:

# View configuration
# View a summary of the current configuration
ws-ckpt config
# View the global configuration
ws-ckpt config -g
# View the configuration for a specific workspace
ws-ckpt config -w ~/proj

# Modify configuration
# === Global configuration ===
# Enable automatic snapshot cleanup and keep the last 10 snapshots
ws-ckpt config -g --enable-auto-cleanup --auto-cleanup-keep 10
# Enable automatic snapshot cleanup and keep snapshots from the last 7 days
ws-ckpt config -g --enable-auto-cleanup --auto-cleanup-keep 7d
# Disable global automatic snapshot cleanup
ws-ckpt config -g --disable-auto-cleanup

# === Per-workspace configuration (overrides global) ===
# Enable cleanup for a specific workspace and keep the last 10 snapshots
ws-ckpt config -w ~/proj --enable-auto-cleanup --auto-cleanup-keep 10
# Enable cleanup for a specific workspace and keep snapshots from the last 7 days
ws-ckpt config -w ~/proj --enable-auto-cleanup --auto-cleanup-keep 7d
# Disable cleanup for a specific workspace
ws-ckpt config -w ~/proj --disable-auto-cleanup