[docs] Explore workspace-backed internal HTML apps

[mmabrouk]

Context

Agenta can preview agent-created HTML files, but the preview removes author-provided JavaScript before loading the page. This keeps an untrusted preview safe, but it means an agent cannot create a small interactive application that reads and updates files in the same workspace.

This draft gives Arda a concrete design to evaluate. It does not implement the feature or commit us to shipping it.

What this proposes

Add an explicit Run mode beside the existing Preview and Source views.

Preview would keep its current sanitization. Run would execute the HTML in the existing sandboxed iframe and inject a narrow window.arg.fs bridge. The application would request file operations through postMessage; the parent renderer would validate the iframe, path, scope, and access level before calling the mounts API.

For example:

await window.arg.ready
const board = await window.arg.fs.readJSON("board.json")
board.columns[0].cards.push({ id: crypto.randomUUID(), text: "Review the idea" })
await window.arg.fs.writeJSON("board.json", board)

The iframe would never receive an API token or arbitrary authenticated HTTP access.

The document covers:

• The current HtmlBody behavior and the smallest likely integration point.
• The proposed user flow and versioned browser contract.
• The sandbox, credential, path, and permission boundaries.
• A staged path from read-only access to explicit folder-scoped writes.
• Open ownership and security questions for Arda.

Prototype evidence

A standalone prototype verified the message protocol and a mount-shaped file adapter. Ten logic checks covered handshake, read, list, exists, write persistence, stable errors, read-only enforcement, refresh behavior, and remove. Static checks confirmed that the bridge runs before application code and that the iframe omits allow-same-origin.

The prototype did not run against Agenta's real mounts API and has not had a browser security review. Those gaps are explicit in the design.

Tests

Documentation-only change.

• Read back the committed file from the branch.
• Compared the branch with main: one new document, 204 lines, no unrelated changes.
• Checked the current HtmlBody, iframe sandbox, and drive media code before writing the proposal.

How to review

1. Read Current behavior to confirm the description matches renderers.tsx.
2. Review Proposed browser contract as the public API generated applications would depend on.
3. Review Security model, especially iframe flags and folder path normalization.
4. Answer or amend Questions for Arda.
5. Decide whether the first engineering experiment should be read-only or include explicit write access.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
agenta-documentation	Ready	Preview	Sep 4, 2026 11:07am UTC

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}