From 46599f8bd86c7e6a69a10f45580f8eddcd15f1b8 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 21:26:11 +0000 Subject: [PATCH 1/7] docs(cloud-agents): document customizing workspace snapshots Add a new page under cloud-agents/handoff documenting how to customize the end-of-run snapshot pipeline that backs local-to-cloud and cloud-to-cloud handoff. Targets self-hosted and CLI users who run outside the bundled warp-agent-docker image and need to provide their own declarations script (or a static declarations file) for handoff to work. The page covers: - When to customize (custom Docker image, Direct backend, unmanaged oz agent run in CI) - The two env vars Warp respects (OZ_SNAPSHOT_DECLARATIONS_SCRIPT, OZ_SNAPSHOT_DECLARATIONS_FILE) - The JSONL declarations file format (v1 schema, repo vs file kinds) - A minimal bash script template + the static declarations file pattern (no script needed) - --no-snapshot for disabling snapshots per run Wire the new page into the Handoff sidebar group and add single-sentence cross-links from local-to-cloud, cloud-to-cloud, self-hosting/unmanaged, and self-hosting/index so readers arriving from any of those entry points can find it. Co-Authored-By: Oz --- .../cloud-agents/handoff/cloud-to-cloud.mdx | 2 +- .../cloud-agents/handoff/local-to-cloud.mdx | 2 +- .../cloud-agents/handoff/snapshots.mdx | 135 ++++++++++++++++++ .../cloud-agents/self-hosting/index.mdx | 1 + .../cloud-agents/self-hosting/unmanaged.mdx | 2 + src/sidebar.ts | 1 + 6 files changed, 141 insertions(+), 2 deletions(-) create mode 100644 src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx index 157138b8..bd36b50b 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -19,7 +19,7 @@ Use this handoff direction when: When you send a follow-up to a run whose session has ended, the run continues with: * **The same conversation** - The follow-up is appended to the same conversation. From your perspective, the run is one continuous conversation across sessions. -* **The prior workspace state** - The prior session's repository changes (tracked and untracked) are restored before the agent answers your follow-up. For git-managed sessions, the new session continues on the same Git branch. +* **The prior workspace state** - The prior session's repository changes (tracked and untracked) are restored before the agent answers your follow-up. For git-managed sessions, the new session continues on the same Git branch. You can [customize which repositories and files get snapshotted](/agent-platform/cloud-agents/handoff/snapshots/) when running outside the bundled cloud agent image. * **Stable run identity** - The run's ID, task, creator, environment, schedule trigger, and integration source are preserved. Compute usage is recorded per session but rolls up to the same run. If applying any change fails, the agent reports what couldn't be applied and proceeds with what it could rather than starting over silently. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx index 76c636f7..9dcc34bb 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx @@ -22,7 +22,7 @@ Use this handoff direction when: When you hand off from local to cloud, the receiving cloud agent inherits: * **A forked conversation** - Warp forks your local conversation so the cloud agent inherits the full transcript without modifying the source. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) for related sync behavior. -* **A workspace snapshot** - Warp captures your uncommitted repository changes — both tracked modifications and untracked files — and packages them for the cloud agent. The cloud agent applies them before answering your follow-up. +* **A workspace snapshot** - Warp captures your uncommitted repository changes — both tracked modifications and untracked files — and packages them for the cloud agent. The cloud agent applies them before answering your follow-up. You can [customize which repositories and files get snapshotted](/agent-platform/cloud-agents/handoff/snapshots/) when running outside the bundled cloud agent image. * **Conversation attachments** - Files attached to the local conversation remain available in the cloud run. If applying any change fails in the cloud run, the cloud agent reports what couldn't be applied and proceeds with what it could rather than silently dropping changes. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx new file mode 100644 index 00000000..0b7b05a8 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx @@ -0,0 +1,135 @@ +--- +title: Customizing workspace snapshots +description: >- + Customize which repositories and files Warp snapshots at the end of a cloud + agent run, so handoff continues to work outside the bundled warp-agent-docker + image. +sidebar: + label: "Snapshots" +--- + +Workspace snapshots are how [handoff](/agent-platform/cloud-agents/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 run (or a local **Continue locally** session) can apply them. + +The bundled [`warp-agent-docker`](https://github.com/warpdotdev/warp-agent-docker) 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](/agent-platform/cloud-agents/self-hosting/managed-direct/), or as an [unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/) `oz agent run` in CI. + +## When to customize snapshots + +The default snapshotting behavior is sufficient when your cloud agent runs use the bundled `warp-agent-docker` image and operate entirely inside the assigned workspace. Customize snapshots when: + +* **You use a custom Docker base image** that doesn't include the bundled `snapshot-declarations.sh` script. +* **You run cloud agents on a self-hosted Direct backend** or as unmanaged `oz agent run` invocations, where the bundled script isn't on disk. +* **You want to snapshot a fixed set of repositories or files** outside the agent's workspace (for example, a sibling repo that the agent reads but doesn't `cd` into). + +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 from an empty workspace. + +## How snapshotting works + +At the end of every cloud agent run, Warp: + +1. **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. +2. **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. +3. **Reads the declarations file.** Warp parses the JSONL output (described below) and uploads the listed repositories and files. + +You can skip the script entirely and pre-populate the declarations file yourself — see [Use a static declarations file](#use-a-static-declarations-file) below. + +Snapshotting is automatically enabled for cloud agent runs when cloud conversations are enabled. To turn it off for a specific run, pass `--no-snapshot` to `oz agent run` or `oz agent run-cloud`. + +## Environment variables + +* **`OZ_SNAPSHOT_DECLARATIONS_SCRIPT`** - Absolute path to the script Warp invokes at the end of each cloud agent run. The bundled `warp-agent-docker` 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). Warp sets this to a per-run path by default. Override it only when you want Warp to read from a static, pre-populated declarations file instead of running a script. + +## Declarations file format + +The declarations file is UTF-8 JSONL — one JSON object per non-empty line: + +```json title="snapshot-declarations.jsonl" +{"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 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 bundled implementation at [`warpdotdev/warp-agent-docker/snapshot-declarations.sh`](https://github.com/warpdotdev/warp-agent-docker/blob/main/snapshot-declarations.sh) is a good reference; the minimal pattern looks like this: + +```bash title="snapshot-declarations.sh" +#!/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. +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)" + printf '{"version":1,"kind":"repo","path":"%s"}\n' "$repo_root" \ + >> "$OZ_SNAPSHOT_DECLARATIONS_FILE" + done +``` + +Then point Warp at it by exporting `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` in the environment your cloud agent runs in: + +```bash +export OZ_SNAPSHOT_DECLARATIONS_SCRIPT=/path/to/snapshot-declarations.sh +``` + +For a managed [Direct backend](/agent-platform/cloud-agents/self-hosting/managed-direct/) worker, set this in the worker's `setup_command` or via the worker's `environment` config so it's present when the agent process starts. + +## 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: + +```json title="/etc/oz/snapshot-declarations.jsonl" +{"version":1,"kind":"repo","path":"/workspace/my-repo"} +{"version":1,"kind":"repo","path":"/workspace/shared-libs"} +``` + +Then point Warp at the file directly: + +```bash +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: + +```bash +oz agent run-cloud --prompt "Fix the failing test" --no-snapshot +``` + +Snapshotting is also skipped automatically when cloud conversations are disabled for the team. + +## Related pages + +* [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/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](/agent-platform/cloud-agents/handoff/cloud-to-cloud/) - Continue a finished cloud run; the prior session's workspace snapshot is what gets restored. +* [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) - Architecture decision guide for self-hosted workers, where customizing snapshots is most often needed. +* [Unmanaged architecture](/agent-platform/cloud-agents/self-hosting/unmanaged/) - Run `oz agent run` in CI, Kubernetes, or your dev environment outside the bundled image. +* [Oz CLI](/reference/cli/) - Full reference for `oz agent run` and `oz agent run-cloud`, including the `--no-snapshot` flag. diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx index f46d4783..cbb98904 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx @@ -216,3 +216,4 @@ For infrastructure-level observability, the `oz-agent-worker` daemon can export * [Troubleshooting](/agent-platform/cloud-agents/self-hosting/troubleshooting/) — Worker won't start, tasks not picked up, and other common issues. * [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) — How self-hosting compares to CLI-only and Warp-hosted deployment. * [Environments](/agent-platform/cloud-agents/environments/) — Define the runtime context for agent tasks. +* [Customizing workspace snapshots](/agent-platform/cloud-agents/handoff/snapshots/) — Configure end-of-run snapshots so handoff works when running outside the bundled cloud agent image. diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx index a912561f..29e23231 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx @@ -126,6 +126,8 @@ Unmanaged agents are tracked on Warp's backend. Each run creates a persistent se Unmanaged sessions benefit from the same shared configuration as other cloud agent runs — [MCP servers](/agent-platform/cloud-agents/mcp/), [secrets](/agent-platform/cloud-agents/secrets/), Warp Drive context, and saved prompts all apply. +Unmanaged runs don't ship with the bundled `warp-agent-docker` declarations script, so end-of-run workspace snapshots are a no-op by default. To enable [handoff](/agent-platform/cloud-agents/handoff/) into a follow-up run, see [Customizing workspace snapshots](/agent-platform/cloud-agents/handoff/snapshots/). + --- ## Related pages diff --git a/src/sidebar.ts b/src/sidebar.ts index cabd7404..f24cf1be 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -362,6 +362,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'agent-platform/cloud-agents/handoff', label: 'Overview' }, { slug: 'agent-platform/cloud-agents/handoff/local-to-cloud', label: 'Local to cloud' }, { slug: 'agent-platform/cloud-agents/handoff/cloud-to-cloud', label: 'Cloud to cloud' }, + { slug: 'agent-platform/cloud-agents/handoff/snapshots', label: 'Snapshots' }, ], }, 'agent-platform/cloud-agents/secrets', From 530e05ffcecf64ca1c9d5cc76e01256ffc871e24 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 21:34:26 +0000 Subject: [PATCH 2/7] docs(cloud-agents): address self-audit findings on snapshots page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Drop the "Continue locally" mention from the intro. Cloud-to-local handoff doesn't apply workspace patches to a local checkout (per handoff/index.mdx), so the claim was misleading. - Replace "empty workspace" with "without the prior session's uncommitted changes". The cloud workspace isn't empty without a snapshot — the environment still clones repos at HEAD; what's missing is the uncommitted delta. - Restructure "How snapshotting works" to lead with the two modes (script-driven vs static) before walking through each one. Removes the implicit assumption that the script always runs. - Drop the setup_command half of the Direct backend tip. setup_command injects env vars via OZ_ENVIRONMENT_FILE, which is more indirection than this page should explain — just point at `environment` config. - Remove the local-to-cloud cross-link to the snapshots page. The local-to-cloud path uses upload_snapshot_for_handoff() with Vec arguments, not OZ_SNAPSHOT_DECLARATIONS_SCRIPT, so the cross-link could mislead readers. cloud-to-cloud, self-hosting/unmanaged, and self-hosting/index still link to the page. Co-Authored-By: Oz --- .../cloud-agents/handoff/local-to-cloud.mdx | 2 +- .../cloud-agents/handoff/snapshots.mdx | 27 ++++++++++++------- 2 files changed, 19 insertions(+), 10 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx index 9dcc34bb..76c636f7 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx @@ -22,7 +22,7 @@ Use this handoff direction when: When you hand off from local to cloud, the receiving cloud agent inherits: * **A forked conversation** - Warp forks your local conversation so the cloud agent inherits the full transcript without modifying the source. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) for related sync behavior. -* **A workspace snapshot** - Warp captures your uncommitted repository changes — both tracked modifications and untracked files — and packages them for the cloud agent. The cloud agent applies them before answering your follow-up. You can [customize which repositories and files get snapshotted](/agent-platform/cloud-agents/handoff/snapshots/) when running outside the bundled cloud agent image. +* **A workspace snapshot** - Warp captures your uncommitted repository changes — both tracked modifications and untracked files — and packages them for the cloud agent. The cloud agent applies them before answering your follow-up. * **Conversation attachments** - Files attached to the local conversation remain available in the cloud run. If applying any change fails in the cloud run, the cloud agent reports what couldn't be applied and proceeds with what it could rather than silently dropping changes. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx index 0b7b05a8..c725b9d6 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx @@ -8,7 +8,7 @@ sidebar: label: "Snapshots" --- -Workspace snapshots are how [handoff](/agent-platform/cloud-agents/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 run (or a local **Continue locally** session) can apply them. +Workspace snapshots are how [handoff](/agent-platform/cloud-agents/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. The bundled [`warp-agent-docker`](https://github.com/warpdotdev/warp-agent-docker) 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](/agent-platform/cloud-agents/self-hosting/managed-direct/), or as an [unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/) `oz agent run` in CI. @@ -20,19 +20,28 @@ The default snapshotting behavior is sufficient when your cloud agent runs use t * **You run cloud agents on a self-hosted Direct backend** or as unmanaged `oz agent run` invocations, where the bundled script isn't on disk. * **You want to snapshot a fixed set of repositories or files** outside the agent's workspace (for example, a sibling repo that the agent reads but doesn't `cd` into). -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 from an empty workspace. +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 -At the end of every cloud agent run, Warp: +There are two ways to tell Warp what to snapshot at the end of a cloud agent run: -1. **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. -2. **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. -3. **Reads the declarations file.** Warp parses the JSONL output (described below) and uploads the listed repositories and files. +* **Script-driven** (default in the bundled image) - Warp invokes a declarations script 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). +* **Static** - You pre-populate the declarations file yourself and skip the script. Use this when the same set of repos and files should be snapshotted on every run. -You can skip the script entirely and pre-populate the declarations file yourself — see [Use a static declarations file](#use-a-static-declarations-file) below. +### Script-driven flow -Snapshotting is automatically enabled for cloud agent runs when cloud conversations are enabled. To turn it off for a specific run, pass `--no-snapshot` to `oz agent run` or `oz agent run-cloud`. +1. **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. +2. **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. +3. **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](#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](#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](#disable-snapshots) below. ## Environment variables @@ -96,7 +105,7 @@ Then point Warp at it by exporting `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` in the envi export OZ_SNAPSHOT_DECLARATIONS_SCRIPT=/path/to/snapshot-declarations.sh ``` -For a managed [Direct backend](/agent-platform/cloud-agents/self-hosting/managed-direct/) worker, set this in the worker's `setup_command` or via the worker's `environment` config so it's present when the agent process starts. +For a managed [Direct backend](/agent-platform/cloud-agents/self-hosting/managed-direct/) worker, set it via the worker's `environment` config so it's present when the agent process starts. ## Use a static declarations file From 5c23a3b7b40d6199876f9991e185255226874e02 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 22:08:06 +0000 Subject: [PATCH 3/7] docs(cloud-agents): address Oz review on snapshots page Three suggestions from the Oz review on PR #105, all accepted: 1. Add a security caution after the declarations format section. Explicit warning that declared `file` paths are uploaded verbatim and `repo` paths upload the git diff (tracked + untracked, non-gitignored). Tells users to keep secrets, credentials, and API tokens out of declared `file` entries before copying the pattern. 2. Escape JSON metacharacters in repo paths in the bash template. The previous example printf'd `repo_root` straight into JSON; a path containing `"` or `\` would produce malformed JSON that Warp skips with a WARN. Added a sed pass that escapes `\` first, then `"`, matching the bot's suggested patch. 3. Drop the "including the --no-snapshot flag" claim from the Oz CLI Related pages bullet. /reference/cli/ doesn't document the flag today, so the claim sent readers somewhere that couldn't answer the flag-specific question. The flag is already covered on this page in the Disable snapshots section. Co-Authored-By: Oz --- .../cloud-agents/handoff/snapshots.mdx | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx index c725b9d6..5efc1738 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx @@ -72,6 +72,10 @@ A few rules to follow when writing declarations: Malformed lines (invalid JSON, missing fields, unknown `kind`, non-absolute path) are logged as warnings and skipped; they never abort the upload. +:::caution +**Declared paths are uploaded to Warp.** `file` entries upload the file's contents verbatim, and `repo` entries upload the repo's git diff (tracked changes plus untracked, non-gitignored files). Before declaring logs, scratch files, or other agent outputs as `file` entries, make sure they don't contain secrets, credentials, API tokens, or other sensitive data. +::: + ## Write a custom declarations script A custom script writes one JSON line per repository or file it wants Warp to snapshot, then exits. The bundled implementation at [`warpdotdev/warp-agent-docker/snapshot-declarations.sh`](https://github.com/warpdotdev/warp-agent-docker/blob/main/snapshot-declarations.sh) is a good reference; the minimal pattern looks like this: @@ -90,11 +94,14 @@ 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. +# 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)" - printf '{"version":1,"kind":"repo","path":"%s"}\n' "$repo_root" \ + 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 ``` @@ -141,4 +148,4 @@ Snapshotting is also skipped automatically when cloud conversations are disabled * [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/) - Continue a finished cloud run; the prior session's workspace snapshot is what gets restored. * [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) - Architecture decision guide for self-hosted workers, where customizing snapshots is most often needed. * [Unmanaged architecture](/agent-platform/cloud-agents/self-hosting/unmanaged/) - Run `oz agent run` in CI, Kubernetes, or your dev environment outside the bundled image. -* [Oz CLI](/reference/cli/) - Full reference for `oz agent run` and `oz agent run-cloud`, including the `--no-snapshot` flag. +* [Oz CLI](/reference/cli/) - Full reference for `oz agent run` and `oz agent run-cloud`. From ea9bbd5e905aad09496dd9297354de8942a5c866 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 22:13:00 +0000 Subject: [PATCH 4/7] docs(cloud-agents): align 'untracked files' precision with caution The "Prefer `repo` over `file`" rule said `repo` entries pick up "tracked changes plus untracked files" while the security caution right below said "tracked changes plus untracked, non-gitignored files". The caution is the accurate one (matches `git ls-files --others --exclude-standard` in `app/src/ai/agent_sdk/driver/snapshot.rs::build_repo_patch`), so tighten the rule to match. Co-Authored-By: Oz --- .../docs/agent-platform/cloud-agents/handoff/snapshots.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx index 5efc1738..70316a88 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx @@ -66,7 +66,7 @@ Each line has exactly these fields: 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 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. +* **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`. From a00d291abad585fd5ed19e23fd5202681807af67 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 22:21:11 +0000 Subject: [PATCH 5/7] docs(cloud-agents): scrub private warp-agent-docker links from snapshots docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The two GitHub URLs the new snapshots page used were both pointing at warpdotdev/warp-agent-docker, which is a private repo — anonymous visitors get HTTP 404. Replaced both with link-free user-facing prose and reworded all text mentions of the internal repo name. Specifically: * snapshots.mdx frontmatter description: "bundled warp-agent-docker image" → "bundled cloud agent image". * snapshots.mdx intro paragraph: drop the link to the private repo root; refer to "Warp's bundled cloud agent image" instead. * snapshots.mdx "When to customize" intro: replace "bundled warp-agent-docker image" with "bundled cloud agent image". * snapshots.mdx env-var reference: same swap for OZ_SNAPSHOT_DECLARATIONS_SCRIPT description. * snapshots.mdx "Write a custom declarations script": drop the link to the private snapshot-declarations.sh file; the sentence now just introduces the minimal pattern. * snapshots.mdx: add a :::note callout under the script example describing what the bundled image's richer implementation does beyond the minimal pattern (OZ_SNAPSHOT_SCAN_ROOTS override, jq for JSON encoding, dedup against existing repo declarations) so power users know what's available without us pointing at private artifacts. * unmanaged.mdx Tracking and observability cross-link: drop the "warp-agent-docker" qualifier. Verified with grep: no more "warp-agent-docker" references anywhere in src/content/docs/. Co-Authored-By: Oz --- .../cloud-agents/handoff/snapshots.mdx | 14 +++++++++----- .../cloud-agents/self-hosting/unmanaged.mdx | 2 +- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx index 70316a88..0c9b23b4 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx @@ -2,7 +2,7 @@ title: Customizing workspace snapshots description: >- Customize which repositories and files Warp snapshots at the end of a cloud - agent run, so handoff continues to work outside the bundled warp-agent-docker + agent run, so handoff continues to work outside the bundled cloud agent image. sidebar: label: "Snapshots" @@ -10,11 +10,11 @@ sidebar: Workspace snapshots are how [handoff](/agent-platform/cloud-agents/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. -The bundled [`warp-agent-docker`](https://github.com/warpdotdev/warp-agent-docker) 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](/agent-platform/cloud-agents/self-hosting/managed-direct/), or as an [unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/) `oz agent run` in CI. +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](/agent-platform/cloud-agents/self-hosting/managed-direct/), or as an [unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/) `oz agent run` in CI. ## When to customize snapshots -The default snapshotting behavior is sufficient when your cloud agent runs use the bundled `warp-agent-docker` image and operate entirely inside the assigned workspace. Customize snapshots when: +The default snapshotting behavior is sufficient when your cloud agent runs use the bundled cloud agent image and operate entirely inside the assigned workspace. Customize snapshots when: * **You use a custom Docker base image** that doesn't include the bundled `snapshot-declarations.sh` script. * **You run cloud agents on a self-hosted Direct backend** or as unmanaged `oz agent run` invocations, where the bundled script isn't on disk. @@ -45,7 +45,7 @@ In both flows, snapshotting is automatically enabled for cloud agent runs when c ## Environment variables -* **`OZ_SNAPSHOT_DECLARATIONS_SCRIPT`** - Absolute path to the script Warp invokes at the end of each cloud agent run. The bundled `warp-agent-docker` image sets this automatically. Set it yourself when running outside the bundled image. +* **`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). Warp sets this to a per-run path by default. Override it only when you want Warp to read from a static, pre-populated declarations file instead of running a script. ## Declarations file format @@ -78,7 +78,7 @@ Malformed lines (invalid JSON, missing fields, unknown `kind`, non-absolute path ## Write a custom declarations script -A custom script writes one JSON line per repository or file it wants Warp to snapshot, then exits. The bundled implementation at [`warpdotdev/warp-agent-docker/snapshot-declarations.sh`](https://github.com/warpdotdev/warp-agent-docker/blob/main/snapshot-declarations.sh) is a good reference; the minimal pattern looks like this: +A custom script writes one JSON line per repository or file it wants Warp to snapshot, then exits. The minimal pattern looks like this: ```bash title="snapshot-declarations.sh" #!/bin/bash @@ -114,6 +114,10 @@ export OZ_SNAPSHOT_DECLARATIONS_SCRIPT=/path/to/snapshot-declarations.sh For a managed [Direct backend](/agent-platform/cloud-agents/self-hosting/managed-direct/) worker, set it via the worker's `environment` config so it's present when the agent process starts. +:::note +The declarations script bundled in Warp's cloud agent image is a richer version of the example above: it also 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 instead of `sed`-based escaping, and dedupes against repo declarations already written in the same run so repeated invocations stay additive. +::: + ## 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: diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx index 29e23231..84d725d2 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx @@ -126,7 +126,7 @@ Unmanaged agents are tracked on Warp's backend. Each run creates a persistent se Unmanaged sessions benefit from the same shared configuration as other cloud agent runs — [MCP servers](/agent-platform/cloud-agents/mcp/), [secrets](/agent-platform/cloud-agents/secrets/), Warp Drive context, and saved prompts all apply. -Unmanaged runs don't ship with the bundled `warp-agent-docker` declarations script, so end-of-run workspace snapshots are a no-op by default. To enable [handoff](/agent-platform/cloud-agents/handoff/) into a follow-up run, see [Customizing workspace snapshots](/agent-platform/cloud-agents/handoff/snapshots/). +Unmanaged runs don't ship with the bundled declarations script, so end-of-run workspace snapshots are a no-op by default. To enable [handoff](/agent-platform/cloud-agents/handoff/) into a follow-up run, see [Customizing workspace snapshots](/agent-platform/cloud-agents/handoff/snapshots/). --- From a1e84dee18b952f135419c04f594a28e224e3add Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 23:32:34 +0000 Subject: [PATCH 6/7] docs(cloud-agents): add full bundled snapshot script alongside minimal example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per Harry's Slack OK on showing the full script ("from a security POV, definitely no issues with showing the entire script... any user who cared could easily find the script by just running a cloud agent and cat-ing it out"), include the canonical declarations script Warp invokes inside the bundled cloud agent image in addition to (not replacing) the minimal sed-based example. Changes to snapshots.mdx: * Keep the minimal sed-based example unchanged. It's a clean starting point for users adapting a custom script. * Add a new "### The full bundled script" subsection right after the Direct backend tip. It introduces the canonical script in prose, then shows it verbatim in a second bash code block. * Add a :::note flagging that OZ_SNAPSHOT_JQ defaults to /agent/tools/jq (an image-only path). External users adapting the script need to put jq on PATH or override OZ_SNAPSHOT_JQ. * Drop the previous :::note that summarized what the bundled script did extra — the same information is now visible directly in the script. Co-Authored-By: Oz --- .../cloud-agents/handoff/snapshots.mdx | 80 ++++++++++++++++++- 1 file changed, 79 insertions(+), 1 deletion(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx index 0c9b23b4..548d5518 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx @@ -114,10 +114,88 @@ export OZ_SNAPSHOT_DECLARATIONS_SCRIPT=/path/to/snapshot-declarations.sh For a managed [Direct backend](/agent-platform/cloud-agents/self-hosting/managed-direct/) 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. + :::note -The declarations script bundled in Warp's cloud agent image is a richer version of the example above: it also 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 instead of `sed`-based escaping, and dedupes against repo declarations already written in the same run so repeated invocations stay additive. +The bundled script defaults `OZ_SNAPSHOT_JQ` to `/agent/tools/jq`, which only exists inside Warp's cloud agent image. If you adapt this script for a different image or for an unmanaged `oz agent run`, put `jq` on `PATH` or set `OZ_SNAPSHOT_JQ` to its absolute path. ::: +```bash title="snapshot-declarations.sh" +#!/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: From bea343eca817b1d55fc161143453ddafc93802d5 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 23:49:31 +0000 Subject: [PATCH 7/7] docs(cloud-agents): address Harry's review on snapshots page Apply Harry's four outstanding review comments on PR #105: - "When to customize snapshots" no longer duplicates the example list from the intro paragraph. Reframed around user intent rather than failure modes: outside-bundled-image, repos/files outside the workspace, and dynamic scripted behavior. - Replaced the "snapshot a fixed set of repositories or files" bullet with a broader "dynamic snapshotting behavior" item that calls out that the script can implement any logic the operator wants, not just a fixed list. - The "Script-driven" bullet under "How snapshotting works" now names OZ_SNAPSHOT_DECLARATIONS_SCRIPT inline, so readers know the script path is overridable before they reach the Script-driven flow subsection. The "Static" bullet now names OZ_SNAPSHOT_DECLARATIONS_FILE for symmetry. - The OZ_SNAPSHOT_DECLARATIONS_FILE entry in the Environment variables section now spells out its relationship with OZ_SNAPSHOT_DECLARATIONS_SCRIPT: when the script var is set Warp picks a per-run path and exports it to the script; users can also override the file path themselves so both Warp and the script use a path they control (or to drive the static, no-script flow). Co-Authored-By: Oz --- .../cloud-agents/handoff/snapshots.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx index 548d5518..30cbebae 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx @@ -14,11 +14,11 @@ Warp's bundled cloud agent image ships with a declarations script that snapshots ## When to customize snapshots -The default snapshotting behavior is sufficient when your cloud agent runs use the bundled cloud agent image and operate entirely inside the assigned workspace. Customize snapshots when: +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 use a custom Docker base image** that doesn't include the bundled `snapshot-declarations.sh` script. -* **You run cloud agents on a self-hosted Direct backend** or as unmanaged `oz agent run` invocations, where the bundled script isn't on disk. -* **You want to snapshot a fixed set of repositories or files** outside the agent's workspace (for example, a sibling repo that the agent reads but doesn't `cd` into). +* **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. @@ -26,8 +26,8 @@ If you don't customize snapshots in any of these cases, the run still completes 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 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). -* **Static** - You pre-populate the declarations file yourself and skip the script. Use this when the same set of repos and files should be snapshotted on every 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 @@ -46,7 +46,7 @@ In both flows, snapshotting is automatically enabled for cloud agent runs when c ## 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). Warp sets this to a per-run path by default. Override it only when you want Warp to read from a static, pre-populated declarations file instead of running a script. +* **`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