Skip to content

Commit 4a4cba4

Browse files
bradenbizbradenbiz
committed
docs(remote): describe recording and script download recovery
1 parent 081d14b commit 4a4cba4

3 files changed

Lines changed: 11 additions & 5 deletions

File tree

‎packages/command-surface/src/schema/command-overrides.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = {
160160
text: {
161161
summary: 'Expose a local daemon through an HTTP tunnel',
162162
description:
163-
'Expose the local daemon HTTP contract through a tunnel-friendly reverse proxy.\n\nRun this on the host that has access to simulators/devices, expose the printed local proxy URL through a tunnel, then point another machine at the tunnel URL with connect proxy.\n\nThe proxy starts or reuses a local HTTP daemon, accepts /health, /rpc, /upload and resumable /upload/* routes, and /artifacts plus /artifacts/*, and also accepts the same routes under /agent-device/*. Health is unauthenticated for reachability probes. Other routes require the generated bearer token printed at startup, or the explicit --daemon-auth-token value when provided. The proxy rewrites authorized client requests to the upstream daemon token instead of exposing the local daemon token.\n\nFor a TLS-terminated tunnel, set --public-origin to the public HTTP(S) origin, for example --public-origin https://public.example:8443. Forwarded and X-Forwarded-* headers do not select upload ticket origins. For an ephemeral tunnel, obtain its public name first, then configure and restart the proxy. Without a fixed origin, Node uses the actual socket scheme and validated Host.\n\nUse the /agent-device base path when connecting through cloudflared, ngrok, or another shared origin. Treat the bearer token as a secret; anyone with it can control the proxied daemon. This direct proxy flow does not use agent-device auth.\n\nRemote captures write generated artifacts on the daemon. Screenshot, recording, performance, and trace paths select downloads on the client; they never select host files. Direct RPC callers download returned artifact IDs through /artifacts/<id>. Remote requests ignore client cwd and refuse host tooling paths, --launch-console, and script publication.\n\nExamples:\n cloudflared tunnel --url http://127.0.0.1:4310\n agent-device proxy --port 4310 --public-origin https://example.trycloudflare.com\n agent-device connect proxy --daemon-base-url https://example.trycloudflare.com/agent-device --daemon-auth-token <token>',
163+
'Expose the local daemon HTTP contract through a tunnel-friendly reverse proxy.\n\nRun this on the host that has access to simulators/devices, expose the printed local proxy URL through a tunnel, then point another machine at the tunnel URL with connect proxy.\n\nThe proxy starts or reuses a local HTTP daemon, accepts /health, /rpc, /upload and resumable /upload/* routes, and /artifacts plus /artifacts/*, and also accepts the same routes under /agent-device/*. Health is unauthenticated for reachability probes. Other routes require the generated bearer token printed at startup, or the explicit --daemon-auth-token value when provided. The proxy rewrites authorized client requests to the upstream daemon token instead of exposing the local daemon token.\n\nFor a TLS-terminated tunnel, set --public-origin to the public HTTP(S) origin, for example --public-origin https://public.example:8443. Forwarded and X-Forwarded-* headers do not select upload ticket origins. For an ephemeral tunnel, obtain its public name first, then configure and restart the proxy. Without a fixed origin, Node uses the actual socket scheme and validated Host.\n\nUse the /agent-device base path when connecting through cloudflared, ngrok, or another shared origin. Treat the bearer token as a secret; anyone with it can control the proxied daemon. This direct proxy flow does not use agent-device auth.\n\nRemote captures write generated artifacts on the daemon. Screenshot, recording, performance, and trace paths select downloads on the client; they never select host files. Direct RPC callers download returned artifact IDs through /artifacts/<id>. Remote requests ignore client cwd and refuse host tooling paths and --launch-console. With a supported daemon, a fresh open --save-script arms ordinary recording; session save-script downloads a session-script artifact while keeping the session open. Repeat session save-script to retry a retained download, with --force to replace an existing caller file. Remote close/replay --save-script and script publication in batch steps remain refused.\n\nExamples:\n cloudflared tunnel --url http://127.0.0.1:4310\n agent-device proxy --port 4310 --public-origin https://example.trycloudflare.com\n agent-device connect proxy --daemon-base-url https://example.trycloudflare.com/agent-device --daemon-auth-token <token>',
164164
},
165165
listUsageOverride: 'proxy',
166166
allowedFlags: ['proxyHost', 'proxyPort', 'publicOrigin', 'daemonAuthToken', 'stateDir'],

‎website/docs/docs/remote-proxy.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -104,12 +104,17 @@ while the artifact remains in inventory.
104104
Each download has a 15-minute maximum lifetime. When it reaches that limit, the daemon cancels it
105105
and cleans up after its pipeline stops.
106106

107-
Remote requests ignore `meta.cwd`. They refuse host tooling paths, `--launch-console`, and script
108-
publication with reason `REMOTE_HOST_INPUT_DENIED`. They also refuse daemon host paths as `install`
107+
A fresh `open --save-script` can arm ordinary remote recording.
108+
`session save-script` publishes a `session-script` artifact and downloads it while keeping the session open.
109+
Repeat the command to download the retained immutable script again; pass `--force` to replace an existing caller file.
110+
Publish before closing. Remote `close --save-script`, `replay --save-script`, and script publication in batch steps remain refused.
111+
112+
Remote requests ignore `meta.cwd`. They refuse host tooling paths and `--launch-console`
113+
with reason `REMOTE_HOST_INPUT_DENIED`. They also refuse daemon host paths as `install`
109114
and `reinstall` binaries, `push` payload files, and xctrace template files. `open` targets and launch
110115
URLs cannot use the `file:` scheme. Serve local web content over HTTP(S) instead. Upload binaries with the
111116
client, send `push` payloads as inline JSON, and name xctrace templates. Omit these inputs, or use a local daemon for
112-
host tooling and script publication. Test suite artifacts also use a daemon-chosen output root.
117+
host tooling. Test suite artifacts also use a daemon-chosen output root.
113118

114119
## Human takeover
115120

‎website/docs/docs/replay-e2e.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,8 +73,9 @@ agent-device open Settings --platform ios --session e2e --save-script ./workflow
7373
- Missing parent directories are created.
7474
- With a local daemon, the script is written on the daemon host.
7575
- With a remote daemon that advertises `activeScriptArtifacts` in `/health`, a fresh `open --save-script=journey.ad` arms recording. Run `session save-script` to download the `.ad` to that caller-side path while keeping the session open. An already-open unarmed session cannot export earlier history.
76+
- A bare remote `open --save-script` chooses `recording-<timestamp>.ad` in the caller working directory.
7677
- Publish before closing. Remote `close --save-script` and `replay --save-script` remain unsupported; plain `close` discards an unpublished remote recording and does not download a script.
77-
- The daemon allocates its own output path and returns the published script as an authenticated artifact. The client downloads atomically and preserves an existing output unless `--force` authorizes replacement. If download or local publication fails, the error reports an artifact ID for retry through the same authenticated endpoint and tenant/lease routing. Script artifacts remain downloadable for the existing 15-minute artifact lifetime.
78+
- The daemon allocates its own output path and returns the published script as an authenticated artifact. The client downloads atomically and preserves an existing output unless `--force` authorizes replacement. If download or local publication fails, repeat `session save-script` while the artifact is retained. Use `--force` to replace an existing caller file, or name another caller destination. The retry downloads the same immutable script; it does not record later actions. The error also reports an artifact ID for direct authenticated download. Script artifacts remain downloadable for the existing 15-minute artifact lifetime.
7879
- Upgrade the client and owning daemon together. Through a proxy, the upstream daemon must advertise the capability. The client does not take over or restart an externally owned daemon. Remote batch steps do not arm or publish scripts.
7980
- For a bare file name that could be read as another argument, use `--save-script=workflow.ad` or a path-like value such as `./workflow.ad`.
8081

0 commit comments

Comments
 (0)