Skip to content

Commit a00d291

Browse files
hongyi-chenoz-agent
andcommitted
docs(cloud-agents): scrub private warp-agent-docker links from snapshots docs
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 <oz-agent@warp.dev>
1 parent ea9bbd5 commit a00d291

2 files changed

Lines changed: 10 additions & 6 deletions

File tree

src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,19 @@
22
title: Customizing workspace snapshots
33
description: >-
44
Customize which repositories and files Warp snapshots at the end of a cloud
5-
agent run, so handoff continues to work outside the bundled warp-agent-docker
5+
agent run, so handoff continues to work outside the bundled cloud agent
66
image.
77
sidebar:
88
label: "Snapshots"
99
---
1010

1111
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.
1212

13-
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.
13+
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.
1414

1515
## When to customize snapshots
1616

17-
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:
17+
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:
1818

1919
* **You use a custom Docker base image** that doesn't include the bundled `snapshot-declarations.sh` script.
2020
* **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
4545

4646
## Environment variables
4747

48-
* **`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.
48+
* **`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.
4949
* **`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.
5050

5151
## Declarations file format
@@ -78,7 +78,7 @@ Malformed lines (invalid JSON, missing fields, unknown `kind`, non-absolute path
7878

7979
## Write a custom declarations script
8080

81-
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:
81+
A custom script writes one JSON line per repository or file it wants Warp to snapshot, then exits. The minimal pattern looks like this:
8282

8383
```bash title="snapshot-declarations.sh"
8484
#!/bin/bash
@@ -114,6 +114,10 @@ export OZ_SNAPSHOT_DECLARATIONS_SCRIPT=/path/to/snapshot-declarations.sh
114114

115115
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.
116116

117+
:::note
118+
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.
119+
:::
120+
117121
## Use a static declarations file
118122

119123
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:

src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ Unmanaged agents are tracked on Warp's backend. Each run creates a persistent se
126126

127127
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.
128128

129-
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/).
129+
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/).
130130

131131
---
132132

0 commit comments

Comments
 (0)