Agents > Handoff

Customizing workspace snapshots

Customize which repositories and files Warp snapshots at the end of a cloud agent run, so handoff continues to work outside the bundled cloud agent image.

Workspace snapshots are how handoff carries repository changes and other workspace state across cloud agent runs. At the end of every cloud agent run, Warp asks a small declarations script which repositories and files to snapshot, then uploads the resulting git diffs and file contents so the next cloud agent run can apply them.

Warp’s bundled cloud agent image ships with a declarations script that snapshots every git repository under the agent’s workspace, so most cloud agent runs need no configuration. This page is for the cases where you need to customize what gets snapshotted — for example, when running cloud agents in a custom Docker image, on a self-hosted Direct backend, or as an unmanaged oz agent run in CI.

When to customize snapshots

The default snapshotting behavior covers the most common case: snapshot every git repository the agent worked on, inside the bundled cloud agent image. Customize snapshots when you need different behavior:

You’re running outside the bundled image — for example, a custom Docker base image, a self-hosted Direct backend, or unmanaged oz agent run invocations — where Warp’s default snapshot-declarations.sh isn’t on disk.
You want to snapshot repos or files outside the agent’s workspace — for example, a sibling repo the agent reads but doesn’t cd into, or a log file the agent writes to /tmp.
You want dynamic snapshotting behavior — because the declarations file is generated by a script that Warp runs, you can script any logic you want (filter by git status, dedupe against a baseline, emit a fixed list, etc.) rather than being limited to a static set of paths.

If you don’t customize snapshots in any of these cases, the run still completes — Warp just uploads nothing, and handoff into the next run starts without the prior session’s uncommitted changes.

How snapshotting works

There are two ways to tell Warp what to snapshot at the end of a cloud agent run:

Script-driven (default in the bundled image) - Warp invokes a declarations script (configured via the OZ_SNAPSHOT_DECLARATIONS_SCRIPT environment variable) that emits one JSON line per repository or file to snapshot. Use this when the set of repos isn’t fixed ahead of time (for example, the agent may git init a new directory during its work) or when you want any other dynamic logic to decide what to snapshot.
Static - You pre-populate the declarations file yourself (at the path given by OZ_SNAPSHOT_DECLARATIONS_FILE) and skip the script. Use this when the same set of repos and files should be snapshotted on every run.

Script-driven flow

Warp invokes your declarations script. The script path comes from the OZ_SNAPSHOT_DECLARATIONS_SCRIPT environment variable. Warp runs it with the agent’s workspace as the current directory.
Warp passes a per-run output file. Warp sets OZ_SNAPSHOT_DECLARATIONS_FILE to an absolute path the script must write to. Each run gets its own file so concurrent runs don’t clobber each other.
Warp reads the declarations file. Warp parses the JSONL output (described below) and uploads the listed repositories and files.

See Write a custom declarations script for the full pattern.

Static flow

Set OZ_SNAPSHOT_DECLARATIONS_FILE to a path you’ve already populated and leave OZ_SNAPSHOT_DECLARATIONS_SCRIPT unset. Warp reads the file directly with no script invocation. See Use a static declarations file for the full pattern.

In both flows, snapshotting is automatically enabled for cloud agent runs when cloud conversations are enabled, and can be turned off per run with --no-snapshot. See Disable snapshots below.

Environment variables

OZ_SNAPSHOT_DECLARATIONS_SCRIPT - Absolute path to the script Warp invokes at the end of each cloud agent run. The bundled cloud agent image sets this automatically. Set it yourself when running outside the bundled image.
OZ_SNAPSHOT_DECLARATIONS_FILE - Absolute path to the JSONL file the script writes to (and Warp reads from). When OZ_SNAPSHOT_DECLARATIONS_SCRIPT is set, Warp picks a per-run path by default and exports it to the script. Set or override this variable yourself when you want Warp to read from a static, pre-populated declarations file instead of running a script, or whenever you want both Warp and the script to use a specific path you control.

Declarations file format

The declarations file is UTF-8 JSONL — one JSON object per non-empty line:

{"version":1,"kind":"repo","path":"/workspace/my-repo"}
{"version":1,"kind":"file","path":"/tmp/agent-output.log"}

Each line has exactly these fields:

version - Always 1. Reserved for future schema versions.
kind - Either "repo" or "file".
path - A non-empty absolute path.

A few rules to follow when writing declarations:

Paths must be absolute. Relative paths are rejected and logged as malformed.
Prefer repo over file for paths inside a repository. Warp generates a git diff for each repo entry (tracked changes plus untracked, non-gitignored files), so individual file entries inside that repo are redundant and dropped before upload. Including a repo entry is also more extensible than enumerating files.
Repos are diffed, not copied wholesale. Only changed files are uploaded for each repo entry, so listing a large repository is cheap when the agent’s changes are small.
file entries are for paths outside any declared repo — for example, logs the agent wrote to /tmp or scratch files in $HOME.

Malformed lines (invalid JSON, missing fields, unknown kind, non-absolute path) are logged as warnings and skipped; they never abort the upload.

Write a custom declarations script

A custom script writes one JSON line per repository or file it wants Warp to snapshot, then exits. The minimal pattern looks like this:

#!/bin/bash
set -euo pipefail

# Warp sets this to a per-run output path. Fail loudly if it's missing,
# so a misconfigured runner doesn't silently overwrite a shared file.
if [ -z "${OZ_SNAPSHOT_DECLARATIONS_FILE:-}" ]; then
  echo "OZ_SNAPSHOT_DECLARATIONS_FILE must be set" >&2
  exit 1
fi

mkdir -p "$(dirname "$OZ_SNAPSHOT_DECLARATIONS_FILE")"

# Find every git repo under the agent's workspace and emit a JSONL
# repo declaration for each one. Escape backslashes and double quotes in
# the path before writing so paths containing those characters don't
# produce malformed JSON (which Warp skips with a warning).
find "$PWD" -type d -name .git -prune -print 2>/dev/null \
  | while IFS= read -r git_dir; do
      repo_root="$(cd "$(dirname "$git_dir")" && pwd)"
      repo_json="$(printf '%s' "$repo_root" | sed 's/\\/\\\\/g; s/"/\\"/g')"
      printf '{"version":1,"kind":"repo","path":"%s"}\n' "$repo_json" \
        >> "$OZ_SNAPSHOT_DECLARATIONS_FILE"
    done

Then point Warp at it by exporting OZ_SNAPSHOT_DECLARATIONS_SCRIPT in the environment your cloud agent runs in:

export OZ_SNAPSHOT_DECLARATIONS_SCRIPT=/path/to/snapshot-declarations.sh

For a managed Direct backend worker, set it via the worker’s environment config so it’s present when the agent process starts.

The full bundled script

For reference, this is the canonical declarations script Warp invokes inside the bundled cloud agent image. It’s a richer version of the minimal example above: it honors a colon-separated OZ_SNAPSHOT_SCAN_ROOTS override for operators who need to scan repos outside the default workspace, uses jq for canonical JSON encoding (which handles " and \ escaping for you), and dedupes against repo declarations already written in the same run so repeated invocations stay additive.

#!/bin/bash
# Generates the declarations file consumed by the end-of-run snapshot upload pipeline.
#
# Scans one or more roots for `.git` directories and appends one JSON object per
# newly-discovered repository to the declarations file.
#
# Scan root selection (in order of precedence):
#   - OZ_SNAPSHOT_SCAN_ROOTS: colon-separated list of absolute paths. Operators can use this
#     to target repos outside the default workspace.
#   - $PWD: the Rust driver sets this to the agent's workspace via `Command::current_dir`
#     before invoking the script, so the default scan root is always the assigned workspace.
#
# Output file:
#   - OZ_SNAPSHOT_DECLARATIONS_FILE must be set. The Rust driver sets this to a per-run path
#     so concurrent runs don't clobber each other.
#   - The file is created if missing, and appended to if it already exists. Existing lines are
#     never rewritten, so operator-authored declarations are preserved.
#   - Repeated invocations within a single run skip already-emitted repo declarations so the
#     upload pipeline can stay additive without duplicating identical generated entries.

set -euo pipefail

SCAN_ROOTS_RAW="${OZ_SNAPSHOT_SCAN_ROOTS:-$PWD}"
IFS=':' read -r -a SCAN_ROOTS <<< "$SCAN_ROOTS_RAW"

if [ -z "${OZ_SNAPSHOT_DECLARATIONS_FILE:-}" ]; then
    echo "OZ_SNAPSHOT_DECLARATIONS_FILE must be set" >&2
    exit 1
fi

DECL_FILE="$OZ_SNAPSHOT_DECLARATIONS_FILE"
JQ="${OZ_SNAPSHOT_JQ:-/agent/tools/jq}"
mkdir -p "$(dirname "$DECL_FILE")"
touch "$DECL_FILE"

# Dedup set. Seed from repo declarations already emitted by this script so a repeated
# invocation within the same run doesn't re-emit repos it already discovered earlier.
# Keep the full canonical JSON line as the key; this lets us preserve unrelated JSONL entries
# verbatim while ensuring identical generated declarations are emitted at most once.
SEEN_FILE="$(mktemp)"
trap 'rm -f "$SEEN_FILE"' EXIT
"$JQ" --raw-input --compact-output '
    fromjson?
    | select(
        type == "object"
        and (. | keys_unsorted | sort == ["kind", "path", "version"])
        and .version == 1
        and .kind == "repo"
        and (.path | type == "string")
    )
    | { version: 1, kind: "repo", path: .path }
' "$DECL_FILE" > "$SEEN_FILE"

repo_declaration_for_path() {
    "$JQ" --compact-output --null-input \
        --arg path "$1" \
        '{ version: 1, kind: "repo", path: $path }'
}

for root in "${SCAN_ROOTS[@]}"; do
    [ -d "$root" ] || continue
    while IFS= read -r git_dir; do
        repo_root="$(cd "$(dirname "$git_dir")" && pwd)"
        repo_declaration="$(repo_declaration_for_path "$repo_root")"
        if grep -Fxq -- "$repo_declaration" "$SEEN_FILE"; then
            continue
        fi
        printf '%s\n' "$repo_declaration" >> "$SEEN_FILE"
        printf '%s\n' "$repo_declaration" >> "$DECL_FILE"
    done < <(find "$root" -type d -name .git -prune -print 2>/dev/null)
done

Use a static declarations file

If the same set of repositories or files should be snapshotted on every run (for example, an unmanaged GitHub Actions job operating on a known checkout), you can skip the script entirely and pre-populate a JSONL file:

{"version":1,"kind":"repo","path":"/workspace/my-repo"}
{"version":1,"kind":"repo","path":"/workspace/shared-libs"}

Then point Warp at the file directly:

export OZ_SNAPSHOT_DECLARATIONS_FILE=/etc/oz/snapshot-declarations.jsonl
# Do not set OZ_SNAPSHOT_DECLARATIONS_SCRIPT in this mode.

Warp reads the file at end-of-run and uploads the listed repos and files. Because the file is the same on every run, this is best for environments where the workspace layout is fixed.

Disable snapshots

To opt out of snapshotting for a single run, pass --no-snapshot to the CLI:

oz agent run-cloud --prompt "Fix the failing test" --no-snapshot

Snapshotting is also skipped automatically when cloud conversations are disabled for the team.

Handoff from local to cloud - Promote a local conversation to a cloud run; the workspace snapshot is what carries your uncommitted changes across.
Handoff from cloud to cloud - Continue a finished cloud run; the prior session’s workspace snapshot is what gets restored.
Self-hosting overview - Architecture decision guide for self-hosted workers, where customizing snapshots is most often needed.
Unmanaged architecture - Run oz agent run in CI, Kubernetes, or your dev environment outside the bundled image.
Oz CLI - Full reference for oz agent run and oz agent run-cloud.