Repository navigation
docs(docs/coder-agents): document embedded previews - #31287
DanielleMaywood wants to merge 1 commit into
Conversation
Docs previewCheck off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here. |
ibetitsmike
left a comment
There was a problem hiding this comment.
Adversarial security review — #31287 (docs)
Part of the stack review; the stack-level roll-up (findings S1/S2, method, verified negatives) is on #31282. Every literal claim in the new docs text checked out against the implementation (root-only / not plan mode, port range, .html/.htm/index.html, Linux/macOS only with Windows failing closed, file-only vs directory, no listings, no unpublish, lifetime = agent lifetime, refresh-on-recall). The issues are omissions, plus overstatements that live in the PR bodies / code comments rather than the user docs.
Unverified (single reviewer) — P3
- Who can view a preview is not stated. "Owner-only" (#31283 body,
request.go:327,preview.go:133,ARCHITECTURE.md:1014) is overstated: the gate isapplication_connecton the workspace (db.go:370) — site owners (unless--disable-owner-workspace-access), workspace-ACLuse/adminusers, and custom org roles grantingworkspace.application_connectall pass (validated). Org admins do not. portpreviews are plain port-forward URLs and inherit port-share levels (request.go:357-400); a public share makes the "preview" unauthenticated. "Port shares do not apply" is true only forpathmode. Users should be told that the Preview tab is not a sharing boundary.- "Eligible files" is undefined. Actual rule: every regular, non-dot-component file at any depth, any type (
config.json,*.pem, …), symlinks never followed, hardlinks served, no re-validation,/or$HOMEpublishable if they containindex.html. The only guard is the LLM-facing hint in the tool description. - Previews are model-authored content rendered automatically in the dashboard on the wildcard app domain, sharing the app session cookie with every other app of the user (S1). Admins should know the prompt-injection implications and that
cors_behavior=passthrutemplates bypass the preview-origin CORS rule. - No way to disable
open_preview: unconditionally appended (turn_environment.go:2427); MCP allow/deny lists don't cover built-ins; no experiment flag; the port-5 listener is always on; a missing wildcard hostname only hides the UI — publication still occurs. This contradicts the docs' "tool configuration from the control plane" promise; either document the limitation or add a switch.
nit
- 16-publication cap, no unpublish, and stable path-derived IDs (republish after agent restart keeps the URL) are undocumented in both the docs and the tool description.
- "workspace agent" vs the docs' established "workspace daemon"; "only the agent can publish them again" is ambiguous (the model republishes via the tool).
coderd/x/chatd/ARCHITECTURE.md:1014<!-- TODO -->left by #31284 is not resolved here and repeats "owner-only".- #31283's known limitations (older wsproxies don't route previews; 63-char DNS label ⇒ agent/workspace/user names ≤ ~32 chars for the 5-segment hostname; http-only port previews) are absent from user docs.
24f1ddd to
6a6bc51
Compare
ea75919 to
37a2a8a
Compare
37a2a8a to
539f020
Compare
539f020 to
29ca139
Compare
29ca139 to
229d4d3
Compare
229d4d3 to
2c52e96
Compare
ibetitsmike
left a comment
There was a problem hiding this comment.
Follow-up (re-checked at 2c52e96): one isolation claim is now demonstrably false, one risk is missing — P2 (docs)
The rewrite fixed most of the earlier omissions (who can view, port shares, which files are served, hard links, secrets warning, prompt-injection mention). Two remaining issues, both verified against the code on #31283:
-
docs/ai-coder/agents/index.md:295— "Coder rejects cross-origin requests from a preview page to other workspace apps, such as form posts andfetchcalls." This is not what is enforced. Validated end-to-end: the rejection applies only to subdomain apps and only when the browser sends a well-formed previewOrigin. Requests with noOrigin(every no-corsGET: images, scripts, frames),Origin: null(nested sandboxed frame,no-referrerform posts), and any request to a path-based app (/@user/ws/apps/..., which carries the full session cookie) are delivered. An operator reading the current sentence would reasonably treat untrusted preview content as unable to send authenticated traffic to their dev apps. Suggested wording until the implementation is tightened:Preview pages use separate app hostnames and run in a sandbox that prevents them from navigating the dashboard or opening pop-ups. Coder refuses subdomain app requests whose
Originheader identifies a preview page, which blocks ordinaryfetchcalls and form posts from reading or reaching other subdomain apps. This does not block every request: requests without anOriginheader, withOrigin: null, or to path-based apps can still reach those apps with your app session. Treat preview content as untrusted. -
Missing: preview HTML/JS executes in the viewer's browser, not in the workspace. The sandbox sets no
connect-src/default-src, so a malicious preview can send anything it can read (published content, data typed into it) to external hosts and can probe services reachable from the viewer's network — workspace egress rules do not apply, and it can register a service worker on the preview origin that outlives the publication (#31283). Given the surrounding text emphasises prompt-injection risk and workspace isolation, this distinction should be explicit.
(Both points were also raised by a second independent review of the rebased stack; the path-app case was found while reconciling the two.)
2c52e96 to
9c74a77
Compare
|
@codex review
|
0c3cbf9 to
b9eef0c
Compare
|
@codex review
|
|
Codex Review: Didn't find any major issues. What shall we delve into next? Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
b9eef0c to
01dca33
Compare
291bcef to
67692a6
Compare
|
/coder-agents-review |
|
Chat: Review posted | View chat Review history
deep-review v0.13.0 | Round 8 | Last posted: Round 8, 26 findings (1 P2, 10 P3, 9 P4, 6 Nit), APPROVE. Review Finding inventoryFindings
Contested and acknowledgedCRF-2 (Nit, index.md:313) - "workspace agent" vs "workspace daemon"
CRF-3 (Nit, architecture.md:133) - Root-only/non-plan-mode restriction restated
CRF-10 (P3, index.md:292) - Secrets warning addresses the reader and gives no remedy
CRF-11 (P3, index.md:302) - Port previews break apps that call other origins; no pointer to ports submenu
CRF-14 (P3, architecture.md:45) - Architecture page omits browser path to daemon HTTP API through app proxy
CRF-16 (P4, index.md:297) - Chat sharing does not share previews
CRF-18 (P4, index.md:314) - 64-path limit shared by every chat on the agent
CRF-21 (Nit, index.md:310) - "active chats" means not archived
CRF-22 (Nit, index.md:313) - "Published files" vs "published paths"
CRF-23 (Nit, index.md:293) - "eligible" undefined term
CRF-43 (P4, index.md:319) - "the agent opens a preview" vs the user opening it
Round logRound 1Full panel (round 1). Netero first pass: 3 Nit, 2 Note, no P0, so the panel ran. Panel: Pen Botter (docs specialist), Kurapika (security claims), Pariston, Mafuuu (core), Leorio, Gon (floor), Razor, Mafu-san, Hisoka (pool), Knov (wildcard). Multi-domain target 9-12 because the docs make security-boundary claims. Law not run (51 effective additions). Result: 1 P2, 9 P3, 5 P4, 6 Nit, 3 Note (body), 11 out of scope. CRF-4 merged into CRF-8. Reviewer verification-only notes (Razor, Mafu-san, Gon, Leorio line 295) are not findings and have no rows. Reviewed against 1780acb..af1e9ca. Round 2Churn guard PROCEED: 11 author fixed, 10 contested, 0 silent. Restructure round: files moved to docs/coder-agents/ and the stacked implementation changed (CSP, preview IDs, popout frame, cookie handling bullet added). Round 3Churn guard PROCEED: CRF-13, CRF-21, CRF-37, CRF-38 author fixed in 0a5736f, 0 silent. Fix round (only fixes, +4 effective lines, no files moved). Round 4Churn guard PROCEED: CRF-40 author fixed in f318f98, 0 silent. Fix round: the only other change is a new sentence at the port bullet saying Coder connects over HTTP, not HTTPS. Round 5Churn guard PROCEED: 0 open findings. Rebase only: the PR diff is identical to R4 (f318f98). The base moved fd5c0c5 to 8cac206; stack changes are a comment edit in exp_chats_previews.go, a comment in openpreview.go, preview cache invalidation in useChatStore.ts, subagent tool status in Tool.tsx/utils.ts, and computer_use provider wording in index.md:264 and architecture.md:174, none touching a documented preview claim. CRF-39 accepted by the author as a known gap without a ticket. Round 6Churn guard PROCEED: 0 open findings. Base moved 8cac206 to 36356bf: the stack replaced auto-open of new previews with a toast (PreviewPanelContext.tsx useNewPreviews, toast.info "The agent shared a preview." with an Open preview action), removed the narrow-window and other-user-read-only suppression, and refactored clearCachedWorkspaceState in turn_environment.go. The PR rewrote two lines in index.md to match. Fix round (two changed lines). Round 7Churn guard PROCEED: CRF-41 author fixed in 5d5a70a (quotes the toast text; author avoided "notification", which the Agents docs use for push and Coder notifications). Base moved 36356bf to 6c17e4e: openpreview.go description now "Offer an embedded preview to the user, who opens it from the chat"; toast ID now includes the workspace ID. Fix round. Round 8Churn guard PROCEED: CRF-43 contested. Base moved 6c17e4e to 8674bea: the toast text changed to "Opened a preview" (PreviewPanelContext.tsx:173). The PR changed only the quoted toast text at index.md:319. Fix round. About deep-reviewCRF = Coder Review Finding (P0-P4, Nit, Note)
|
There was a problem hiding this comment.
This PR documents open_preview and the Preview tab in the Coder Agents docs and narrows two existing network claims. Findings: 1 P2, 9 P3, 5 P4, 6 Nit. Most documented values match the stacked implementation (port range, file filters, 64-path cap, wildcard gate, viewer set, CSP). The P2 and several P3s are cases where the text promises behavior the code does not deliver.
Out of scope (needs a ticket or explicit acceptance by a human):
coderd/x/chatd/ARCHITECTURE.md:1177: theopen_previewsection is still a<!-- TODO -->, so the chatd architecture doc does not describe the preview subsystem.site/src/pages/AgentsPage/AgentChatPage/AgentChatPageView.tsx:418: the add menu offers Preview whenever the chat has a workspace, but without a wildcard access URLopen_previewis never registered, so the tab shows "No previews yet." forever.agent/agentpreview/preview.go:110: preview IDs restart at00000001per agent process and are shared by every chat on the agent, so after a restart one chat's menu entry can serve another chat's files; all path previews also share one browser origin, so they sharelocalStorageand cookies.agent/agentpreview/preview.go:91: a symlinked, hard-linked, or non-regular file is reported as "does not exist or cannot be read", so the model cannot correct the request.coderd/x/chatd/chattool/openpreview.go:56: the 1000 to 65535 range and the 64-path limit are literals repeated acrossopenpreview.go,appurl.go, andpreview.go, so changing either value leaves stale copies in the tool description.docs/admin/networking/wildcard-access-url.md:22: the list of features that need a wildcard access URL omits embedded previews.coderd/workspaceapps/proxy.go:66: the CSP andisFromOtherPreviewcheck apply only to preview hostnames; the agent can serve the same code on another port, where neither applies.agent/agentpreview/preview.go:82: theos.Roothandle keeps serving the original directory inode, so a delete-and-recreate rebuild returns 404 untilopen_previewruns again.agent/agentpreview/preview.go:174: a subdirectory request without a trailing slash returns 404 instead of redirecting to the slash form.coderd/x/chatd/chattool/openpreview.go:98:path.IsAbsrejects native Windows paths such asC:\out\index.html, although the agent's preview code builds for Windows.coderd/coderd.go:948: an administrator can disableopen_previewonly by removing the wildcard access URL, which also disables every subdomain app.
Notes:
docs/ai-coder/agents/index.md:272: root chats in explore mode also lackopen_preview(turn_environment_internal_test.gocaseExploreRoot); "root chats outside plan mode" is accurate only if users cannot create explore-mode root chats, which was not verified.docs/ai-coder/agents/index.md:274: the section mixes developer usage (lines 307 to 316) with administrator security detail (lines 295 to 305) on the overview page, which DOC10 (one audience per page) discourages.- CI reports 20 failed jobs, including
changes,gen, andlint-docs. The job logs could not be read from the review environment. Locally,markdownlint-cli2andmarkdown-table-formatter --checkpass on both files.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
This round reviews the rebased docs at docs/coder-agents/ against the updated stack. Findings: 1 new P3, 1 new P4, plus 2 re-raised (1 P3, 1 Nit).
The fixes for the refresh-after-rebuild, hard-link, navigation, files-added-later, name-length, trailing-slash, menu-after-restart, sharing-level, HTML/CSS expansion and PR-description findings were checked against the code and are correct. The reviewers who raised them accepted the defenses for the workspace agent term, the restated restriction, the secrets warning, port previews calling other origins, the architecture page, chat sharing, the 64-path scope, "Published files" and "eligible". The proxy-version sentence and "active chats" are re-raised on their threads.
Out of scope (needs a ticket or explicit acceptance by a human):
coderd/workspaceapps/proxy.go:65:previewPolicyhas no directive that limits WebRTC, so a prompt-injected preview may be able to send published file contents to an external STUN or TURN host withRTCPeerConnection. Unverified; a browser test that opens a data channel from a preview page would settle it.
🤖 This review was automatically generated with Coder Agents.
|
Not changing: @DanielleMaywood accepted the possible WebRTC exfiltration from previews (
|
|
/coder-agents-review |
There was a problem hiding this comment.
This round checks the fixes in 0a5736f3c1. The proxy-version, "active chats", service-worker and selected-proxy-wildcard findings are fixed and match the code, and the new popout-header and narrow-window sentences also match it. One new P4 remains, on the proxy remedy sentence.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
This round checks f318f98a39. The proxy remedy now sends the user to another dashboard page to choose a proxy, and the new sentence saying port previews connect over plain HTTP matches coderd/workspaceapps/request.go:321. No new findings, and every finding from earlier rounds is fixed or was closed after review of the author's reply. CI was still pending when this round started.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
This head is a rebase: the PR's added and removed lines match the previous head f318f98a39. The stack changes underneath since then are a comment in exp_chats_previews.go, the outdated-agent comment in openpreview.go, preview list invalidation in useChatStore.ts, subagent tool status handling, and the base's computer_use provider wording. The preview claims on the page were rechecked against this head and still hold. No new findings and no open findings. CI was still pending when this round started.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
This round checks the rewrite of the Preview tab paragraph for the stack's switch from auto-opening new previews to a toast. The new lines match PreviewPanelContext.tsx and Tool.tsx: the toast and the tool result's button appear together, both open the Preview tab with the preview selected, and both are absent in archived chats and for previews of an earlier workspace. One P4 on wording.
Out of scope (needs a ticket or explicit acceptance by a human):
coderd/x/chatd/chattool/openpreview.go:76: the tool description still tells the model it will "Open and select an embedded preview for the user", and the tool result header says "Opened <title>" (Tool.tsx:1180), but the stack now only shows a toast, so the model can tell the user a preview is open in the Preview tab when nothing changed on screen.
🤖 This review was automatically generated with Coder Agents.
|
Out-of-scope item on the tool description: fixed in #31284 (1a15f58). The description now says the tool offers an embedded preview to the user, who opens it from the chat, and #31484 extends that to workspace apps.
|
|
/coder-agents-review |
There was a problem hiding this comment.
This round checks the fix for the toast wording in 5d5a70af76. Quoting The agent shared a preview. matches PreviewPanelContext.tsx:173 and follows the style guide's code-font rule for product text, and the reason for avoiding "notification" holds, since getting-started.md:142-148 uses it for push notifications. #31284 fixed the tool description from the previous round's out-of-scope item; the Opened <title> tool result header (Tool.tsx:1180) is unchanged. One new P4 on wording.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
This round checks b1c52aea82. The quoted toast text Opened a preview matches PreviewPanelContext.tsx:173. The "opens" wording at line 319 stays: the page uses "open" for the agent's call, matching the tool name, the Opened <title> tool result header, and the toast, and "shares" would collide with workspace sharing and chat sharing. No new findings and no open findings. CI was still pending when this round started.
🤖 This review was automatically generated with Coder Agents.
Documents
open_previewand the Preview tab in the Coder Agents docs: the port and path modes, what a file or directory publication exposes, the wildcard access URL requirement, which files a directory publishes, who can view previews and what preview pages are restricted from doing (requests stay on the preview's origin, the dashboard stops self-navigation, but a preview opened by its URL can navigate to any URL), the--host-prefix-cookierecommendation, the publication limit and proxy and hostname limitations, and that previews do not survive agent restarts.It also narrows two existing statements, "No additional ports or network paths are introduced" in
architecture.mdand "No additional ports or services are required" in the workspace tools section ofindex.md, to inbound ports, because previews reach the workspace from the browser through the app proxy.Stack (proof of concept for the embedded previews RFC, review bottom-up):
coder_apptabs