Skip to content
Back to search

doop

The open-source alternative to Paper.design. A multiplayer design canvas where humans and AI agents design together, live. MCP built in.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/kgoedecke/doop with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/kgoedecke/doop'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kgoedecke--doop/badge.svg)](/listings/kgoedecke--doop)

HTML

<a href="/listings/kgoedecke--doop"><img src="/api/listings/kgoedecke--doop/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/kgoedecke/doop && cd doop
bun install
bun run dev

Doop builds and installs with [bun](https://bun.sh) (`bun.lock` is the only lockfile); the server itself runs on Node.

- Web app: **http://localhost:4300** - API + WebSocket + MCP server: **http://localhost:4400** (the web port proxies `/api`, `/ws`, `/mcp` to it)

Everything works with no configuration: data persists to an embedded Postgres (PGlite) in `data/pg`, and every optional integration (SMTP, stock photos, object storage, analytics) degrades gracefully until its variable in [.env.example](.env.example) is set. The one you will most likely want is `ANTHROPIC_API_KEY`, which turns on the built-in [Doop Agent](#the-doop-agent) — agents you connect yourself over MCP need no key.

Or self-host the production build with Docker:

BETTER_AUTH_SECRET=$(openssl rand -hex 32) docker compose up -d   # app + Postgres on :4400

Production build without Docker: `bun run build && bun run start` (single server on :4400 serving everything). Set `DATABASE_URL` to use a real Postgres — same code path as PGlite.

Prefer not to run anything? **[doop.design](https://doop.design)** is the hosted version.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,158 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src=".github/assets/banner.png" alt="Doop, the open-source alternative to Paper.design: a live canvas where Claude Code streams a pricing section while ChatGPT and Claude Code cursors move across the frames" width="100%">
  3. </p>
  4. <p align="center">
  5. <a href="https://github.com/kgoedecke/doop/actions/workflows/ci.yml"><img src="https://github.com/kgoedecke/doop/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  6. <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-111110" alt="License: AGPL-3.0"></a>
  7. <a href="https://doop.design"><img src="https://img.shields.io/badge/cloud-doop.design-2743EE" alt="Doop Cloud"></a>
  8. <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-111110" alt="PRs welcome"></a>
  9. <a href="https://discord.com/invite/3AUfXjgVe"><img src="https://img.shields.io/badge/chat-Discord-5865F2" alt="Discord"></a>
  10. </p>
  11. **[Doop](https://doop.design/?utm_source=github) is the open-source alternative to [Paper.design](https://paper.design) — a multiplayer
  12. design canvas for humans _and_ AI agents.** Every design lives on a shareable **Canvas**
  13. (`/c/<id>`) holding **Frames** — artboards that render real HTML in sandboxed iframes. People edit
  14. in the browser; AI agents edit through the built-in **MCP server**, streaming their designs in
  15. live. Everyone sees everything as it happens: cursors, presence, frame edits, agent status, and an
  16. activity feed.
  17. Think of it as Claude Design for whichever agent you already use: **Claude Code, Codex, ChatGPT,
  18. Cursor, OpenCode** or any other MCP client designs on the same canvas, and the built-in Doop Agent
  19. runs on **GPT, Claude, Gemini, DeepSeek, Kimi or Qwen** models
  20. ([every agent and model](#works-with-any-agent)).
  21. <p align="center">
  22. <img src=".github/assets/canvas.png" alt="A Doop canvas with three frames for a travel app (landing hero, mobile itinerary and a booking card) and two collaborators' live cursors" width="100%">
  23. </p>
  24. - **Design with agents, not prompts-and-refresh** — connect Claude Code (or any MCP client) once,
  25. then watch it sketch, stream and self-review designs on your canvas, next to your cursor.
  26. - **A built-in Doop Agent** — queue a card or @mention a role and it designs on its own, no client
  27. to connect. Runs on the model account each user connects (a **ChatGPT subscription**, or an
  28. OpenAI, Claude, Gemini, DeepSeek, Kimi or OpenRouter key), or on the server's `ANTHROPIC_API_KEY` for as many
  29. free tasks as `RESIDENT_TASK_LIMIT` grants (none by default) ([setup](#the-doop-agent)); the
  30. first-canvas welcome performance is scripted and runs without any of it.
  31. - **Pages within a canvas** — organize frames into named pages from the Layers panel. Add, rename,
  32. drag to reorder, double-click to rename, or right-click to rename and delete empty pages.
  33. Page edits support Undo/Redo; selected frames can move between pages. Agents can list pages
  34. with `get_canvas`, manage them with `set_canvas_pages` (passing the original list as
  35. `expectedPages` to protect collaborators), and target frames with `pageId`. Each page can wear
  36. a canvas colour of its own, as in Figma: with nothing selected, the sliders icon on the right
  37. opens the Page panel with its Background swatch (agents: `set_page_background`); cleared, the
  38. page shows the theme paper again.
  39. - **Clickable prototypes** — wire elements to other frames (click, hover, press, key or delay;
  40. navigate, overlay, back, scroll or link, with transitions) in Prototype mode or straight in the
  41. HTML, then click through the flow with Play or share `/c/<id>/proto`. Agents use the same
  42. `data-doop-*` attributes plus `get_prototype` / `set_prototype_start`.
  43. - **A real canvas editor** — draw frames, shapes, pen paths and text, edit any element's fill,
  44. type and flex layout, snap to rulers and guides, zoom from 8% to 1600%
  45. ([the editor](#the-canvas-editor)).
  46. - **True multiplayer** — live cursors, presence, follow mode, per-frame editing indicators,
  47. undo/redo, threaded comments on elements or the canvas, and an activity feed, all over one
  48. WebSocket room.
  49. - **Design memory** — pin exemplar frames, capture decisions, and let the distiller propose durable
  50. style rules that every agent follows.
  51. - **Private by default** — invite collaborators by email or share a link that can view, comment
  52. or edit; agents inherit exactly their human's access.
  53. - **Self-host in one command** — `docker compose up`, or `bun run dev` with zero configuration
  54. (embedded Postgres, no external services required).
  55. ## Works with any agent
  56. Doop isn't tied to one model vendor. Every agent below designs through the same MCP server, works
  57. as the person who connected it, and shows up live on the canvas with its own cursor, status and
  58. tasks. **Connect AI** in the top bar walks you through each one.
  59. <p align="center">
  60. <img src=".github/assets/connect-ai.png" alt="The Connect AI dialog: choose Claude Code, Claude, ChatGPT, Codex, Cursor or any other MCP client" width="100%">
  61. </p>
  62. | Agent | How it connects |
  63. | -------------------------------------------- | ------------------------------------------------------------------------------- |
  64. | Claude Code | `claude mcp add`, OAuth in the browser ([setup](#hook-up-claude-code)) |
  65. | Claude (web and desktop) | **Add to Claude** in Connect AI ([setup](#connect-claude)) |
  66. | Codex (CLI and desktop) | `codex mcp add`, OAuth in the browser ([setup](#connect-an-ai-agent)) |
  67. | ChatGPT | A custom MCP server in ChatGPT, guided by **Connect AI → ChatGPT** |
  68. | Cursor | **Add to Cursor** in Connect AI |
  69. | OpenCode, VS Code Copilot, OpenClaw and more | Any MCP client, over OAuth or with an agent key ([setup](#connect-an-ai-agent)) |
  70. | Headless agents (n8n, Mastra, CI) | An agent key as a bearer header ([setup](#headless-agents-agent-keys)) |
  71. No agent of your own? The built-in [Doop Agent](#the-doop-agent) runs on the model account you
  72. connect: a ChatGPT subscription, or an OpenAI, Claude, Gemini, DeepSeek, Kimi or OpenRouter key.
  73. OpenRouter brings Qwen, GLM, MiniMax and more ([details](#past-the-free-tasks-connect-your-own-chatgpt)).
  74. ## Quickstart
  75. ```bash
  76. git clone https://github.com/kgoedecke/doop && cd doop
  77. bun install
  78. bun run dev
  79. ```
  80. Doop builds and installs with [bun](https://bun.sh) (`bun.lock` is the only
  81. lockfile); the server itself runs on Node.
  82. - Web app: **http://localhost:4300**
  83. - API + WebSocket + MCP server: **http://localhost:4400** (the web port proxies `/api`, `/ws`,
  84. `/mcp`, `/.well-known`, `/i/`, `/ingest` and `/local-agent` to it)
  85. `bun run dev` and `bun run build` also package the Claude Desktop extension with a Node script,
  86. so Node must be on your `PATH` as well.
  87. Everything works with no configuration: data persists to an embedded Postgres (PGlite) in `data/pg`,
  88. and every optional integration (SMTP, stock photos, object storage, analytics) degrades gracefully
  89. until its variable in [.env.example](.env.example) is set ([the ones that matter](#environment-variables)).
  90. The built-in [Doop Agent](#the-doop-agent) runs once a user connects a model account in Settings
  91. (or on the server's `ANTHROPIC_API_KEY` if you raise `RESIDENT_TASK_LIMIT`) — agents you connect
  92. yourself over MCP need no key.
  93. Or self-host the production build with Docker:
  94. ```bash
  95. BETTER_AUTH_SECRET=$(openssl rand -hex 32) docker compose up -d # app + Postgres on :4400
  96. ```
  97. Production build without Docker: `bun run build && bun run start` (single server on :4400 serving
  98. everything). Set `DATABASE_URL` to use a real Postgres — same code path as PGlite.
  99. Prefer not to run anything? **[doop.design](https://doop.design)** is the hosted version.
  100. Once you sign in, Home is where you start: describe what you want and Doop makes a canvas with
  101. drafts queued for the Doop Agent, or pick up one of your canvases, workspaces and connected agents.
  102. <p align="center">
  103. <img src=".github/assets/home.png" alt="Doop's home: the agent prompt with suggestion chips over a gradient wave, the canvas grid, and a rail with workspaces and connected agents" width="100%">
  104. </p>
  105. ## The canvas editor
  106. The bottom toolbar holds the tools; every one has a single-key shortcut. Shapes drawn on the
  107. canvas become standalone elements, and shapes drawn inside a frame become positioned HTML/SVG
  108. layers of that frame, so agents read and edit them like any other markup.
  109. | Tool | Key | What it does |
  110. | ----------- | --- | ------------------------------------------------------------------------------------- |
  111. | Select | V | Click to select, drag the background for a marquee, ⇧/⌘-click to add to the selection |
  112. | Hand | H | Pan (Space or the middle button pans from any tool) |
  113. | Frame | F | Draw an empty frame |
  114. | Rectangle | R | Draw a rectangle |
  115. | Circle | O | Draw a circle or ellipse |
  116. | Vector path | P | Bézier pen: snaps to its own anchors, previews closing the path; Alt skips snapping |
  117. | Text | T | Place a text layer |
  118. | Comment | C | Pin a comment to an element or to the canvas |
  119. - **Frames** — drag to move, pull the corner handle to resize, snap to neighbours and guides.
  120. The Inspector edits name,
  121. position, size and the raw HTML, marks the frame ready for dev, exports it, and pins it as a
  122. style reference; **Version history…** in the frame menu previews and restores earlier designs.
  123. - **Elements inside a frame** — click to select, drag a corner grip or edge to resize (⇧ keeps the
  124. ratio; a `W × H` badge shows the size), drag the element to
  125. move it within or across frames. The **Design** tab edits fill, stroke, text (font, size, weight,
  126. alignment), opacity, corner radius, rotation, position, flex layout (direction, gap, padding,
  127. wrap, alignment) and image fills; **HTML** shows its source; **Prototype** wires interactions. The
  128. floating toolbar adds Comment, **Ask AI** (pre-fills an `@mention`), Code, Edit text and Copy link.
  129. - **Rich text** — double-click text to edit it. Select words and use the formatting toolbar for
  130. bold, italic, underline, strikethrough, bulleted lists or numbered lists. ⌘/Ctrl+B, I and U toggle
  131. inline formatting; ⌘/Ctrl+⇧+7 or 8 toggles numbered or bulleted lists. Enter continues a list;
  132. Enter on an empty item leaves it. With a text layer selected on the canvas, ⌘/Ctrl+B, I, U and
  133. ⌘/Ctrl+⇧+X toggle the whole layer and ⌘/Ctrl+⇧+7 or 8 make it a list, as in Figma. Esc finishes editing; formatting saves with the frame and
  134. supports undo/redo. With words selected, the Design panel's font, size, weight and colour edit
  135. that run alone; selecting the whole layer shows **Mixed** where its runs differ, and a value set
  136. there applies to all of them, as in Figma.
  137. - **Path editing** — double-click a path to drag its anchors and Bézier handles, switch points
  138. between corner and curve, or delete them. Alt moves one handle on its own; ⇧ constrains its angle.
  139. - **Layers** — a searchable tree of pages, frames and elements: drag to reorder or reparent, hide,
  140. lock, collapse, and right-click an element for copy, paste, duplicate, Copy HTML, Copy selector
  141. and Copy link to element.
  142. - **Rulers and guides** — ⇧R shows rulers; drag out of one to add a guide. Guides belong to the page,
  143. undo like any edit, and everything snaps to them within 8 screen pixels.
  144. - **Zoom** — 8% to 1600%. Wheel pans, ⌘/Ctrl + wheel or a pinch zooms; a 1px pixel grid fades in from
  145. 300%. The zoom menu has 50/100/200% presets and the rulers toggle.
  146. - **Panels** — the right side panel has **Agents**, **Comments**, **Activity** and **Memory** tabs;
  147. Layers and the side panel can be resized, and ⌘. hides all UI.
  148. - **Themes** — Light, Dark or System under Settings → Appearance.
  149. - **Phones** — the canvas works on a phone: one-finger pan, pinch zoom, tap to comment, and bottom
  150. sheets for canvas actions, Layers and the Inspector.
  151. | Shortcut | Action |
  152. | ---------------- | ------------------------------------------------------ |
  153. | ⌘Z / ⌘⇧Z (or ⌘Y) | Undo / redo your own edits |
  154. | ⌘C / ⌘V / ⌘D | Copy, paste, duplicate frames or layers |
  155. | ⌫ | Delete the selected element, else the selected frames |
  156. | ⌘⇧H / ⌘⇧L | Hide / lock the selection |
  157. | ⌥↑ / ⌥↓ | Move a layer up or down (Layers panel) |
  158. | ⇧1 / ⇧2 | Zoom to fit everything / the selection |
  159. | ⌘0 / ⌘+ / ⌘− | Zoom to 100%, in, out |
  160. | ⇧R | Toggle rulers |
  161. | ⌘. | Hide or show all UI |
  162. | ⌘⌥↩ | Present from the selected frame (Ctrl+Alt+↩ elsewhere) |
  163. | ⌘K | Open the Agents composer (on Home: the search palette) |
  164. | Esc | Deselect, stop following |
  165. Click a collaborator's avatar to follow their viewport; an agent's avatar flies you to what it is
  166. working on. Placeholder
  167. frames show where an agent that has picked up a card is about to design.
  168. ## Comments, imports and exports
  169. Comment on any element or anywhere on the canvas. The **Comments** tab lists the page's threads
  170. (open or resolved) with their replies. `@mention` an agent role in a comment or a reply (for example
  171. `@doop`) to queue a design card; the agent's answer comes back in the thread. People who miss a
  172. comment get an email digest (opt out under Settings → Account), and canvases opened through a
  173. view-only or comment-only link show a badge and disable editing.
  174. The import source picker offers **Website** (one page, or discover a whole site and pick its pages),
  175. **Live app** (the [sync snippet](#design-sync-push-an-apps-live-screens-onto-a-canvas)), and
  176. **GitHub repo** (through the GitHub App or a fine-grained token: Doop reviews the repo's screens and
  177. components and queues cards for the Doop Agent to sketch them and extract the design system into a
  178. style guide).
  179. Right-click a frame and choose **Export…** to download PNG, JPG or a vector PDF (of the frame, or of
  180. every selected frame as one PDF). **Export** in the top bar binds any frames of the page into one PDF. A progress toast tracks the
  181. render; the desktop app opens its native save panel. Every frame also has a public live image at
  182. `/i/<frameId>.png?scale=2` (or `.jpg`) that re-renders when the design changes, handy as an
  183. `og:image` or in docs.
  184. Figma, Canva and Photoshop (PSD) import and export are currently available in
  185. [Doop Cloud](https://doop.design) and not part of the open source.
  186. ## Integrations
  187. **Integrations** in the rail is where an account connects the outside tools Doop works with:
  188. | Integration | What it does |
  189. | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
  190. | Linear | Read issues through MCP, or delegate an issue to Doop: it designs a canvas and reports the result back to Linear ([setup](docs/linear.md)) |
  191. | Slack | Mention `@Doop` with a brief; it designs a canvas and posts the result in the thread ([setup](docs/slack.md)) |
  192. | Meta Ads | Pull ad creatives onto a canvas on a schedule with an [automation](#automations) |
  193. The Figma integration (import frames as editable HTML, export frames back to Figma) and the Canva
  194. integration (import designs as editable frames, send frames back with live text) are currently
  195. available in [Doop Cloud](https://doop.design) and not part of the open source. A self-hosted
  196. Integrations page shows Linear, Slack and Meta Ads.
  197. <p align="center">
  198. <img src=".github/assets/integrations.png" alt="The Integrations page on Doop Cloud with cards for Figma, Canva, Linear, Slack and Meta Ads" width="100%">
  199. </p>
  200. **Outbound webhooks** (Settings → Webhooks) POST a signed JSON event to your own URL when a
  201. comment is created, replied to or resolved, when a frame is created, or when an agent finishes or
  202. fails a board card, with retries and a test ping ([events and signatures](docs/webhooks.md)).
  203. To reference a specific element in feedback, select it and choose **Copy link**
  204. in its floating toolbar, or right-click its Layers row and choose **Copy link to
  205. element**. Opening the link selects the element and opens its properties on the
  206. correct page. The URL includes the canvas ID, frame ID and URL-encoded CSS
  207. `selector`, so an AI agent can locate it in the frame HTML. Canvas access rules
  208. still apply. Selectors that use element IDs survive layout changes; selectors
  209. based on sibling positions can change when the HTML is restructured.
  210. ## Approve screens for development
  211. Select a frame and turn on **Development → Mark as approved** in the inspector,
  212. or right-click one or more frames and choose **Mark ready for dev**. A green badge
  213. appears above the screen and in Layers. Hover the toggle row or a badge to see
  214. who approved it and when. Turn the toggle off to move an approved screen back to draft.
  215. Changing the HTML or frame dimensions switches an approved screen to **Needs review**;
  216. review it and turn **Mark as approved** on again. Moving, renaming, hiding, locking, or moving
  217. between pages keeps approval. Copies start as drafts. An approval checks the frame
  218. revision so a concurrent edit cannot accidentally be approved, and waits for live
  219. design streams to finish.
  220. Agents can read `approvalStatus` (`draft`, `ready_for_dev`, `needs_review`) and
  221. `approval` attribution in `get_canvas` and `get_frame`. Call
  222. `get_canvas({ canvas_id, approval_status: "ready_for_dev" })` to find approved
  223. screens, then re-read `get_frame` before implementing. Only `ready_for_dev` is
  224. current sign-off. Approval is set by people in the app, or by an agent when a person asks
  225. it to: `set_frame_approval({ frame_id, status: "ready_for_dev" | "draft" })` (MCP and the Doop
  226. Agent) records the approval in that person's name, with the agent shown as "via". An agent
  227. never approves unasked, and automation runs cannot approve. In **Automations**, choose
  228. **Designs are approved** to run a workflow when frames on a selected canvas become
  229. ready for dev. Without an enabled workflow, approval only records sign-off.
  230. The REST equivalent is `PUT /api/frames/:id/approval` with
  231. `{ status: "ready_for_dev" | "draft", expectedUpdatedAt }`. The signed-in user's
  232. identity supplies the attribution; the endpoint uses the same canvas access rules
  233. as editing and returns `409` when the reviewed revision is stale.
  234. ## Clickable prototypes
  235. Turn frames into a flow you can click through. Switch on **Prototype mode** (top bar), pick an
  236. element and add an interaction in its **Prototype** tab, or drag the handle on its right edge
  237. onto another frame. Each interaction is a trigger (click, hover, press, a key or a delay) and an
  238. action (go to a frame, open one as an overlay, go back, close the overlay, scroll, open a link),
  239. with an optional transition: dissolve, slide or push. Connectors on the canvas show where every
  240. element leads, and a **Start** flag marks the frame each page's flow begins on.
  241. <p align="center">
  242. <img src=".github/assets/prototype-canvas.jpg" alt="A travel app prototype in Prototype mode: four iPhone screens with liquid-glass panels over photos, blue connectors from a trending card to the destination screen, from Book stay to the booking sheet overlay and from Confirm and pay to the confirmation, and a Start flag on the first screen" width="100%">
  243. </p>
  244. Press **Play** to run it full screen, or share `/c/<canvas-id>/proto`: the player follows the
  245. same canvas access rules, and the browser's Back and Forward walk the flow. Frames stay live
  246. while you play, so an edit on the canvas shows up on the screen you are looking at.
  247. <p align="center">
  248. <img src=".github/assets/prototype-player.jpg" alt="The prototype player at phone size, three steps of the flow: tapping the Lago di Braies card on Explore, Book stay opening the booking sheet as an overlay, and Confirm and pay dissolving to the confirmation" width="100%">
  249. </p>
  250. Interactions are plain attributes on the element in the frame HTML, so they sync, version and
  251. export with the frame, and agents write them with the same tools they design with:
  252. ```html
  253. <button data-doop-on="click" data-doop-action="navigate:<frameId>" data-doop-transition="push-left">Book stay</button>
  254. ```
  255. Agents check their wiring with `get_prototype`, which flags links to missing frames, and set
  256. the start with `set_prototype_start`. Both the MCP server and the built-in Doop Agent have them.
  257. The full attribute reference is in [`.context/specs/prototyping.md`](.context/specs/prototyping.md).
  258. ## iPhone and iPad app
  259. The SwiftUI iOS app lives in [`ios/`](ios/README.md). Open `ios/Doop.xcodeproj`
  260. in Xcode to run it against Doop Cloud or your own HTTPS server. It uses SwiftUI for the app interface and a native canvas that
  261. renders frames with the Blitz HTML/CSS engine (Rust, no WebKit), over the same REST API and WebSocket rooms. The app is in development;
  262. see the iOS README for validation status and remaining release requirements.
  263. ## Android app
  264. The native Kotlin/Jetpack Compose app lives in [`android/`](android/README.md).
  265. Open that directory in Android Studio or run `./gradlew assembleDebug` from it.
  266. It shares iOS's Blitz/Skia renderer and the existing REST/WebSocket backend, with
  267. native canvas gestures, editing, agent prompts, comments, exports and optional
  268. background task notifications. It targets ARM64 phones and tablets on Android 8+.
  269. See the Android README for setup, tests and release signing.
  270. ## Connect Claude
  271. Choose **Connect AI → Claude → Add to Claude**. On hosted Doop, this opens Claude's
  272. connector form with Doop's name and server URL filled in. Confirm it, sign in to
  273. Doop, then start a new Claude chat and paste the canvas prompt from the dialog.
  274. No file download, terminal or API key needed.
  275. The updated Doop desktop app also offers **Add to Claude** for local and self-hosted
  276. servers: it opens Claude Desktop's extension installer directly, with your server
  277. URL filled in. Confirm the installation in Claude and approve the Doop sign-in.
  278. The online connector needs a publicly reachable HTTPS server; localhost connections
  279. use the desktop app. Manual extension installation remains available as a fallback.
  280. Build and installation details: [`claude-extension/`](claude-extension/README.md).
  281. ## Hook up Claude Code
  282. One command connects Claude Code (or any MCP client) to your canvas:
  283. ```bash
  284. claude mcp add --transport http doop http://localhost:4300/mcp
  285. ```
  286. That triggers the standard MCP OAuth flow — a browser window opens, you approve, and from then on
  287. the agent works **as you**. Ask it to design something on your canvas id and watch it happen live.
  288. Everything in this shot is the real flow: Claude Code announced itself with `set_status`, created a
  289. frame, and is streaming the pricing section in — presence avatar, "for Kai Moreno" attribution,
  290. the frame chip, the working strip, and the task in the Agents panel.
  291. <p align="center">
  292. <img src=".github/assets/claude-code.png" alt="Claude Code connected over MCP OAuth, streaming a pricing-section design into a frame while the humans on the canvas watch it work" width="100%">
  293. </p>
  294. ## Watch an agent design
  295. The first canvas after signup comes with a performance: the Doop Agent streams a welcome
  296. design in while you watch — status in the working strip, a task in the panel, a pulsing border on
  297. the frame it's building.
  298. <p align="center">
  299. <img src=".github/assets/agent-live.png" alt="The Doop Agent streaming a design into a frame, live — working status, agent task panel and pulsing frame border" width="100%">
  300. </p>
  301. That welcome performance is **scripted** (`server/demo.ts`) — a pre-authored frame replayed through
  302. the same machinery real agents use, so it runs with no configuration at all. The Doop Agent proper
  303. needs a key.
  304. ## The Doop Agent
  305. Doop ships a built-in design team that lives in the server and picks work up on its own: queue a
  306. board card, `@mention` a role in a comment, or post task feedback over the API, and it runs
  307. without a human in the loop. Roles (Doop builds; specialists own one pass each — UX, copy, brand,
  308. accessibility) are defined in [`shared/agents.ts`](shared/agents.ts), and a card can be routed
  309. through several in order.
  310. Normally each user's own connected model account pays for their runs (next section). The server
  311. can also pay for a free tier, on Anthropic by default, once `RESIDENT_TASK_LIMIT` is above 0:
  312. ```bash
  313. ANTHROPIC_API_KEY=sk-ant-... # in .env, or the environment of your deployment
  314. ```
  315. Same key gates the **guideline distiller** ([`server/distill.ts`](server/distill.ts)), which proposes
  316. durable style rules from your canvas.
  317. The free tier can run on **Azure OpenAI** instead — useful when your organisation's credits or
  318. compliance rules live there:
  319. ```bash
  320. DOOP_AGENT_PROVIDER=azure
  321. AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com
  322. AZURE_OPENAI_API_KEY=...
  323. AZURE_OPENAI_DEPLOYMENT=my-deployment
  324. ```
  325. The distiller stays on `ANTHROPIC_API_KEY` either way and quietly turns off without it.
  326. ### Past the free tasks: connect your own ChatGPT
  327. When a user's `RESIDENT_TASK_LIMIT` free tasks are gone, they don't lose the agent — they connect a
  328. model account and the Doop Agent keeps running on it. **A connected account takes over immediately**,
  329. from the very next task: the free tier is a trial that gets people here, not a balance to spend down
  330. first, and connecting stops costing the server anything from that moment. The connection is
  331. account-level, so it lives at **/settings** (Home → Settings); the free-tier wall links there rather
  332. than carrying its own copy, and "Connect an AI agent" on a canvas stays about MCP clients only. A
  333. user can connect eight kinds of account; the Gemini cloud pilot and Claude Plan appear only where
  334. the operator or the desktop app provides them:
  335. - **ChatGPT subscription** — OAuth against `auth.openai.com`, then inference through the Codex
  336. backend that Plus/Pro/Business plans include. Tokens live in `model_accounts` and never reach a
  337. browser.
  338. - **OpenAI API key** — pay-as-you-go on the user's own OpenAI account, no subscription involved.
  339. - **OpenRouter API key** — one key for a curated multi-vendor roster: Kimi, Qwen, GLM, DeepSeek,
  340. MiniMax, MiMo and Gemini Flash (the menu lives in
  341. [`shared/modelMenu.ts`](shared/modelMenu.ts)). Models without image input still work, in a
  342. degraded mode: the agent skips screenshot review, verifies through the frame HTML instead, and
  343. the picker labels them "no visual review".
  344. - **Gemini API key** — Google's Gemini models through their OpenAI-compatible endpoint, plus Nano
  345. Banana image generation.
  346. - **DeepSeek API key** — DeepSeek V4.1 Flash (with vision) and V4 Pro (text-only for now) on the
  347. user's own platform.deepseek.com account.
  348. - **Kimi API key** — Moonshot's Kimi K3 models, all with vision, on the user's own
  349. platform.moonshot.ai account. A key from Moonshot's China platform needs an operator to point
  350. `KIMI_CHAT_URL` at `https://api.moonshot.cn/v1/chat/completions`.
  351. - **Kimi Code plan** — a Kimi membership (Plus and up) through a key from the Kimi Code console,
  352. billed to the membership rather than per token. Its own endpoint (`KIMI_CODE_CHAT_URL`,
  353. `api.kimi.ai/coding/v1` overseas) and ids (`k3.1-pro`, `k3.1-pro-highspeed`, `k3`); requests
  354. name Doop in their `User-Agent`, as Kimi Code's terms ask of every third-party tool.
  355. - **Gemini cloud pilot** — an operator-managed prototype running the official Gemini CLI in an
  356. isolated worker using Google sign-in. Disabled by default; see the
  357. [pilot setup and verification guide](docs/gemini-cloud-pilot.md).
  358. - **Claude API key** — pay-as-you-go on the user's own Anthropic account.
  359. - **Claude Plan (desktop app)** — the Doop desktop app runs the Doop Agent through the user's own
  360. local Claude Code login (`claude -p`), with a per-run scoped MCP token. Once switched on it takes
  361. precedence over connected accounts while the app is online. Setup: [`desktop/README.md`](desktop/README.md#local-claude-cli).
  362. The ChatGPT, OpenAI, Claude and Gemini kinds get their model menu from the provider's own
  363. catalog, asked with that account's credential when the picker opens (`server/modelCatalog.ts`,
  364. `GET /api/model-account/models`): the Codex backend's catalog for a ChatGPT subscription (the
  365. same list the Codex CLI reads, asked as `CHATGPT_CODEX_CLIENT_VERSION`), OpenAI's and
  366. Anthropic's `/v1/models`, Gemini's `/v1beta/models`. A newly released model is on the menu
  367. without an upgrade; the curated entries above sit on top as recommendations, a curated tier the
  368. account cannot run is left off, and the curated menu alone is served if the provider cannot be
  369. reached. OpenRouter, DeepSeek, Kimi and Kimi Code stay on their curated rosters, whose hand-checked vision
  370. flags are what the run relies on. DeepSeek and Kimi return their reasoning as `reasoning_content`
  371. and refuse a tool-calling conversation that leaves it out, so the transport keeps it in the run's
  372. history and sends it back on every turn.
  373. Azure OpenAI is deliberately _not_ a connectable account kind, and the OpenRouter/Gemini/DeepSeek/Kimi
  374. endpoints are fixed constants: a user-supplied endpoint would be a URL the server fetches with the run's full
  375. context — an SSRF vector — so custom endpoints stay server-level configuration only.
  376. Either way the user picks their **model tier** in Settings from that provider's curated menu — on
  377. OpenAI, `gpt-6-astra` (the newest flagship; on a ChatGPT subscription it needs Plus or better and
  378. OpenAI is still rolling it out per account), `gpt-5.6-sol` (flagship), `gpt-5.6-terra` (the default
  379. workhorse) or `gpt-5.6-luna` (cheap and fast). They are paying for it, so the choice is theirs;
  380. `DOOP_AGENT_OPENAI_MODEL`, `DOOP_AGENT_OPENROUTER_MODEL`, `DOOP_AGENT_GEMINI_MODEL`,
  381. `DOOP_AGENT_DEEPSEEK_MODEL`, `DOOP_AGENT_KIMI_MODEL` and `DOOP_AGENT_KIMI_CODE_MODEL` only set the default they start on. Note that
  382. `gpt-5.4` and `gpt-5.4-mini` retire from ChatGPT-authenticated Codex on **31 August 2026**, so
  383. pinning a 5.4 id via that env var will break the subscription path after that date.
  384. OpenAI registers no redirect URI for a hosted app, so connecting ChatGPT takes one of three shapes
  385. and Doop picks the cheapest one available:
  386. | Where Doop runs | Flow | What the user does |
  387. | -------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------- |
  388. | Same machine as the browser (dev, self-host) | Loopback catch — Doop holds `127.0.0.1:1455` | Approve in the OpenAI tab. Nothing to copy, no setup |
  389. | Hosted (doop.design) | Device code (`/api/accounts/deviceauth/*`) | Type a short code at `auth.openai.com/codex/device` |
  390. | Device codes disallowed | Browser redirect + paste | Paste the dead `localhost:1455` page's address back into Doop |
  391. The device flow needs **device code authorization** switched on in ChatGPT → Settings → Security
  392. (workspace members need an admin to allow it) — that is why the loopback flow, which needs no
  393. setting at all, stays the default when Doop is local. All three end at the same server-side PKCE
  394. exchange.
  395. > **Before you turn this on for real users:** driving a ChatGPT subscription from a third-party
  396. > server is not something OpenAI's terms sanction, and heavy use can get an account rate-limited or
  397. > suspended. The API-key path is the fully supported alternative and shares all the same code.
  398. > `CHATGPT_CONNECT_DISABLED=1` switches the subscription path off and leaves the key path.
  399. Runs are attributed to the human whose card, comment or feedback they picked up, so the person who
  400. asked for the work is the person whose account runs it. The translation between the agent's
  401. Anthropic-shaped loop and OpenAI's Responses API lives in
  402. [`server/openaiAgent.ts`](server/openaiAgent.ts); which credential a run gets is decided in
  403. [`server/agentModel.ts`](server/agentModel.ts).
  404. **With no server key and no connected account** the Doop Agent is off, and it fails quietly by
  405. design — queued cards and `@mentions` simply wait for some agent to claim them. The startup banner
  406. tells you which state you're in.
  407. **All of this is separate from connecting your own agent.** Claude Code and any other MCP client
  408. authenticate over OAuth and drive the canvas from outside, on your own subscription — never metered.
  409. Three paths, same canvas: the Doop Agent on our key (free tier), the Doop Agent on your key, or your
  410. own agent over MCP.
  411. | Variable | Default | What it does |
  412. | ------------------------------- | --------------------------- | ------------------------------------------------------------------------------------ |
  413. | `DOOP_AGENT_PROVIDER` | `anthropic` | What the free tier runs on: `anthropic` \| `azure` |
  414. | `ANTHROPIC_API_KEY` | _unset_ | Pays for the free Doop Agent tier (default provider) and the distiller |
  415. | `AZURE_OPENAI_ENDPOINT` | _unset_ | The free tier's Azure OpenAI resource, when `DOOP_AGENT_PROVIDER=azure` |
  416. | `AZURE_OPENAI_API_KEY` | _unset_ | A key of that resource |
  417. | `AZURE_OPENAI_DEPLOYMENT` | _unset_ | The deployment the free tier runs on |
  418. | `AZURE_OPENAI_API_VERSION` | _unset_ | Pins an `api-version` query parameter; the v1 surface needs none |
  419. | `AZURE_OPENAI_REASONING_EFFORT` | _unset_ | Reasoning effort on Azure runs; unset sends none (non-reasoning-safe) |
  420. | `RESIDENT_TASK_LIMIT` | `0` | Free Doop Agent tasks per account; `0` means a connected account from the first task |
  421. | `DOOP_AGENT_MODEL` | `claude-opus-5` | Model for the Doop Agent on the server's Anthropic key |
  422. | `DOOP_AGENT_OPENAI_MODEL` | `gpt-5.6-terra` | Default tier on a user's account; each user can pick another in Settings |
  423. | `DOOP_AGENT_OPENAI_EFFORT` | `medium` | Default reasoning effort on a user's OpenAI account; each user can pick low–xhigh |
  424. | `DOOP_AGENT_OPENROUTER_MODEL` | `moonshotai/kimi-k2.6` | Default model on a connected OpenRouter key |
  425. | `DOOP_AGENT_GEMINI_MODEL` | `gemini-3.7-flash` | Default model on a connected Gemini key |
  426. | `DOOP_AGENT_DEEPSEEK_MODEL` | `deepseek-flash` | Default model on a connected DeepSeek key |
  427. | `DOOP_AGENT_KIMI_MODEL` | `kimi-k3.1-pro` | Default model on a connected Kimi key |
  428. | `DOOP_AGENT_KIMI_CODE_MODEL` | `k3.1-pro` | Default model on a connected Kimi Code plan |
  429. | `CHATGPT_CONNECT_DISABLED` | _unset_ | `1` hides the ChatGPT flow, leaving the API-key path |
  430. | `DOOP_DISTILL_MODEL` | `claude-haiku-4-5-20251001` | Model for the guideline distiller |
  431. `RESIDENT_TASK_LIMIT` is the free-tier meter. By default it is `0`: the Doop Agent only runs once
  432. the user connects a model account (any of the kinds above) — a connected
  433. account is never metered. Connecting your own MCP agent does not lift the meter: it runs on your
  434. model when _it_ designs, but resident tasks still bill a credential. Set the limit above 0 to
  435. grant that many free tasks on the server's key; everything that triggers resident work counts,
  436. including feedback and retries. There is no "unlimited" value: self-hosting with your own key, set
  437. it to a large number, since you're paying Anthropic directly either way.
  438. ## Accounts
  439. The web app requires an account (better-auth, email/password — open signup). Your account
  440. name is your identity everywhere: cursors, presence, the activity feed, and feedback
  441. attribution are all server-authoritative from the session, and the WebSocket rejects
  442. unauthenticated joins. **Canvases are private by default**, Figma-style: only the owner
  443. and people they invite (Share → invite by email, existing doop accounts) can open one.
  444. The Share modal also sets what anyone with the link gets: nothing (invite-only, the
  445. default), **view**, **comment** or **edit**. From the same modal an owner can file the canvas
  446. in a workspace or list it in the **Community** gallery (`/community`), where signed-in people
  447. browse published canvases and copy them into their own. Your home screen lists
  448. your own canvases plus ones shared with you (plus unowned legacy ones, claimable there).
  449. Agents connected over MCP act under the account that approved them and get exactly that
  450. user's access.
  451. <p align="center">
  452. <img src=".github/assets/share-modal.png" alt="The share modal: invite collaborators by email, see who has access, and choose what the link grants" width="100%">
  453. </p>
  454. With SMTP configured (`SMTP_HOST` etc. — see [.env.example](.env.example)), signups require email
  455. verification and "forgot password" sends real reset links. Without it, signup stays open and every
  456. email is printed to the server log, links included — the flows still work in development.
  457. Set `SIGNUP_EMAIL_DOMAINS=jointhetroops.com` to restrict new accounts to one email domain, or use a
  458. comma-separated list for several domains. Matching is case-insensitive and exact; existing accounts
  459. are unaffected. Leave it unset to keep public signup open.
  460. Set `REQUIRE_EMAIL_VERIFICATION=false` to let people in before they verify — the link is still
  461. emailed, it just stops gating sign-in. Admin promotion is deliberately not part of that trade:
  462. `ADMIN_EMAILS` only ever promotes a verified address (see below).
  463. If signup or password reset **hangs** rather than failing, the cause is almost always a host that
  464. blocks outbound SMTP: Railway and most PaaS block 25/465/587. Resend also serves 2465/2587, so
  465. `SMTP_PORT=2587` is the usual fix.
  466. Env: `BETTER_AUTH_SECRET` (required in production), `TRUSTED_ORIGINS` (comma-separated,
  467. defaults to the localhost dev origins).
  468. ### Workspaces and billing (Team plan)
  469. A **workspace** is a team's shared home for canvases: everyone in it opens every canvas inside,
  470. with no per-canvas invites. Create one from the sidebar on the home screen, invite people by
  471. email (existing accounts join at once; anyone else joins the moment they sign up with that
  472. address), file canvases in it from the Share modal or the canvas menu ("Move to workspace…"),
  473. and manage people, roles (owner / admin / member) and billing at `/w/<id>`. Agents see workspace
  474. canvases in `list_canvases` and can create into one with `create_canvas`'s `workspace_id`.
  475. Workspaces are the paid part of doop on a hosted deployment. Plans (see `shared/billing.ts`):
  476. | Plan | Price | What it is |
  477. | ---------- | ----------------------------------------- | ------------------------------------------------------------------ |
  478. | Personal | free | Your own canvases, per-canvas invites, agents, community, imports. |
  479. | Team | $20 / seat / month, or $192 / seat / year | Shared workspaces with roles; seats follow the people list. |
  480. | Enterprise | talk to us | SSO, dedicated support, custom terms. |
  481. **Self-hosting: billing is off unless you turn it on.** Without `STRIPE_SECRET_KEY` every
  482. workspace is active and nothing is locked. With it, a workspace must hold a live per-seat
  483. subscription before it can _grow_ — create canvases in it, invite people, take canvases in —
  484. and the upgrade modal appears wherever that is attempted. Canvases already in a workspace stay
  485. open to its members whatever the subscription does (a failed card never locks a team out of its
  486. work). Deleting a workspace hands every canvas back to its owner's personal space and cancels
  487. the subscription.
  488. To enable billing: create the product and prices with `node scripts/stripe-setup.mjs`
  489. (prints `STRIPE_PRICE_TEAM_MONTHLY` / `STRIPE_PRICE_TEAM_YEARLY`), point a Stripe webhook at
  490. `<origin>/stripe/webhook` for `checkout.session.completed` and
  491. `customer.subscription.{created,updated,deleted}`, and set `STRIPE_WEBHOOK_SECRET`. Checkout,
  492. cards, invoices and cancelling all happen on Stripe's hosted pages; the server only mirrors the
  493. subscription onto the workspace (through the webhook, and a direct sync when the browser lands
  494. back from Checkout, so local development works without a tunnel).
  495. ### Instance admins
  496. `ADMIN_EMAILS` (comma-separated) names the accounts that get the `admin` role, applied at
  497. signup, on email verification, and at boot — so you can name an admin before or after they
  498. have an account. **This requires SMTP in production**: an address only identifies someone
  499. once they have proven they own it, and without a mailer signup is open, so anyone could sign
  500. up as your address and take the role with it. A production instance without SMTP promotes
  501. nobody and warns at boot; set the role directly in the database if that is your setup.
  502. Admins get `/admin`: every canvas and account on the instance, and "view as", which hands
  503. them a real but **read-only** 15-minute session as that user. Being an admin does not widen
  504. canvas access itself: the gate in [`server/access.ts`](server/access.ts) is shared with MCP,
  505. so a privileged read there would give every agent holding an admin's token the run of the
  506. instance. View-as sessions cannot write, cannot connect agents, and record who is behind
  507. them in `session.impersonated_by`.
  508. ### SSO (OIDC)
  509. Optional login against an external OIDC provider (Zitadel, Okta, Authentik, Keycloak,
  510. etc.), alongside email/password — not a replacement for it. Set `OIDC_ISSUER`,
  511. `OIDC_CLIENT_ID`, and `OIDC_CLIENT_SECRET` together to enable it; a partial set refuses
  512. to boot rather than run with SSO half-configured. `OIDC_SCOPES` (default
  513. `openid email profile`) and `OIDC_PROVIDER_NAME` (default `SSO`, shown on the login
  514. button — e.g. `Zitadel`) are optional. Signing in via SSO links to an existing
  515. email/password account when the emails match and the provider marks the email
  516. verified, and this works even on an instance with no SMTP configured, where a
  517. local account could otherwise never verify on its own. SSO alone never grants
  518. the admin role, even for an address listed in `ADMIN_EMAILS` — an IdP is not
  519. trusted as an admin-promotion source, only as an email-ownership check;
  520. promotion still requires the normal `ADMIN_EMAILS` path (verified signup, or
  521. `syncAdmins` at boot for an account SSO has since verified).
  522. Env: see the OIDC block in [.env.example](.env.example).
  523. ### Sign in with Google
  524. Optional, alongside email/password and SSO. Create an OAuth client (Web application) in
  525. the [Google Cloud console](https://console.cloud.google.com/apis/credentials), add
  526. `<BETTER_AUTH_URL>/api/auth/callback/google` as an authorised redirect URI, and set
  527. `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` together (one without the other refuses to
  528. boot). The login page shows a "Sign in with Google" button whenever both are set. Account
  529. linking and admin promotion follow the same rules as SSO above; `SIGNUP_EMAIL_DOMAINS`
  530. applies to Google (and SSO) sign-ups exactly as it does to email/password.
  531. ### Sign in with Microsoft
  532. Same shape as Google. Register an app in [Microsoft Entra](https://entra.microsoft.com)
  533. (App registrations, platform Web) with `<BETTER_AUTH_URL>/api/auth/callback/microsoft` as a
  534. redirect URI, create a client secret, and set `MICROSOFT_CLIENT_ID` and
  535. `MICROSOFT_CLIENT_SECRET` together. `MICROSOFT_TENANT_ID` (default `common`, any Microsoft
  536. account) can be `organizations`, `consumers`, or your tenant id to make the button an
  537. org-only door. Microsoft does not assert email ownership unless the app registration's
  538. ID token includes the `email` and `verified_primary_email` optional claims; without them a
  539. Microsoft sign-in still works but only links to an existing account that is already
  540. verified. Everything else (allowlist, admin promotion) follows the SSO rules above.
  541. ### Sign in with Apple
  542. Two independent halves, documented in [.env.example](.env.example). For the web button,
  543. register a Services ID with Sign in with Apple enabled and
  544. `<BETTER_AUTH_URL>/api/auth/callback/apple` as a return URL, then set `APPLE_CLIENT_ID` (the
  545. Services ID) and `APPLE_CLIENT_SECRET` (the client-secret JWT signed with your Sign in with
  546. Apple key, which Apple caps at six months) together. For the iOS app, set
  547. `APPLE_APP_BUNDLE_IDENTIFIER` to the app's bundle id: the app shows the native Sign in with
  548. Apple button and posts the identity token Apple issues for that bundle id to
  549. `/api/auth/sign-in/social`, which the server verifies against Apple's keys. Apple only sends
  550. the person's name on their first sign-in, so the app forwards it then; a later sign-in from a
  551. fresh install leaves the name as stored. Linking and admin promotion follow the SSO rules
  552. above. Apple's "Hide My Email" addresses are on `privaterelay.appleid.com`, which
  553. `SIGNUP_EMAIL_DOMAINS` rejects unless listed.
  554. ## Agent auth (MCP OAuth)
  555. The `/mcp` endpoint requires OAuth. Adding the server in Claude Code / Codex triggers
  556. the standard MCP OAuth flow: a browser window opens, you sign in to Doop and approve,
  557. and the client stores a bearer token. Every tool call then carries your identity —
  558. agent tasks show "for ⟨you⟩" in the Agents panel, and presence tooltips name the owner.
  559. Unauthenticated calls get a 401 whose `WWW-Authenticate` header points at
  560. `/.well-known/oauth-protected-resource/mcp` and asks for `openid profile email offline_access`
  561. (so clients get refresh tokens); that is what kicks off the flow. The approval screen lives at
  562. `/oauth/consent`. Dynamic client registration is enabled, so no manual client setup.
  563. `ping` and `resources/list`/`resources/read` answer without a token, and a banned account's
  564. agents get a 403 even with a valid one.
  565. The endpoint takes `POST` only and answers with plain JSON rather than an SSE stream, which is what
  566. ChatGPT needs. Tool results also carry `structuredContent` for an inline frame-preview card
  567. (`ui://doop/frame-preview-2.html`) in clients that render MCP Apps, such as ChatGPT.
  568. In production also set `BETTER_AUTH_URL` to the public origin — OAuth URLs are built on it.
  569. ## Deploy
  570. The repo ships a production `Dockerfile` (client build + Chromium for frame screenshots).
  571. Any container host works; Railway/Fly are the least friction:
  572. 1. Create the app from this repo (both auto-detect the Dockerfile).
  573. 2. Add a managed Postgres and set `DATABASE_URL`. **Don't skip this in real deployments** —
  574. the PGlite fallback is embedded/single-process and only suits a single instance with a
  575. persistent volume mounted at `/app/data`.
  576. 3. Set `BETTER_AUTH_SECRET` (long random string) and `BETTER_AUTH_URL` (the public origin,
  577. e.g. `https://doop.example.com`). Extra allowed origins: `TRUSTED_ORIGINS` (comma-separated).
  578. 4. Health check: `GET /healthz`. The server trusts one proxy hop (`trust proxy`), so
  579. TLS termination at the platform edge works out of the box.
  580. Local sanity check of the exact production image:
  581. ```bash
  582. docker build -t doop .
  583. docker run -p 4400:4400 -e BETTER_AUTH_URL=http://localhost:4400 -e BETTER_AUTH_SECRET=dev-only doop
  584. ```
  585. ### Environment variables
  586. Every variable is optional except the two marked required in production. Each one is declared and
  587. validated once at boot ([`server/env.ts`](server/env.ts)) and documented in
  588. [`.env.example`](.env.example), which also lists endpoint overrides and other rarely needed knobs.
  589. The server listens on port `4400` on all interfaces by default (IPv6 when available, otherwise IPv4;
  590. most operating systems also accept IPv4 on the default IPv6 listener). Set `HOST=127.0.0.1` to restrict
  591. it to local IPv4 connections, or `HOST=::1` for local IPv6, and `PORT` to change the listening port.
  592. This is the short list a self-hoster usually touches:
  593. | What | Variables | Without them |
  594. | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
  595. | Core | `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL` (both required in production), `DATABASE_URL`, `TRUSTED_ORIGINS`, `HOST`, `PORT` | Embedded PGlite in `data/pg`, localhost origins |
  596. | Sign-in | `OIDC_*`, `GOOGLE_*`, `MICROSOFT_*`, `APPLE_*`, `SIGNUP_EMAIL_DOMAINS`, `ADMIN_EMAILS` ([Accounts](#accounts)) | Email/password only, open signup |
  597. | Email | `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `SMTP_SECURE`, `EMAIL_FROM`, `REQUIRE_EMAIL_VERIFICATION` | Emails print to the server log; no verification |
  598. | Object storage | `BUCKET`, `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`, `ENDPOINT`, `REGION` (any S3-compatible store) | Uploaded assets stored under `data/assets` |
  599. | Doop Agent | `ANTHROPIC_API_KEY`, `RESIDENT_TASK_LIMIT`, `DOOP_AGENT_*`, `AZURE_OPENAI_*` ([The Doop Agent](#the-doop-agent)) | Runs only on accounts users connect |
  600. | Image generation | `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ARK_API_KEY` (Seedream), `DOOP_IMAGE_MODEL` | Runs only on accounts users connect; Seedream off |
  601. | Agent search tools | `PEXELS_API_KEY` (photos), `BRANDFETCH_CLIENT_ID` (logos), `BACKGROUNDS_ORIGIN`, `CONTEXT_DEV_API_KEY` | No photo search; open-source and favicon logos; local Chromium |
  602. | Screenshots | `CHROME_PATH`, `CHROME_NO_SANDBOX` (the Docker image sets both up) | Auto-detected Chrome/Chromium |
  603. | Integrations | `META_APP_ID`/`_SECRET`, `LINEAR_*` ([setup](docs/linear.md)), `SLACK_*` ([setup](docs/slack.md)), `GITHUB_APP_*` | That integration is unavailable; GitHub import uses a personal token |
  604. | Billing | `STRIPE_SECRET_KEY`, `STRIPE_PRICE_TEAM_*`, `STRIPE_WEBHOOK_SECRET` ([billing](#workspaces-and-billing-team-plan)) | Billing off, every workspace active |
  605. | Rate limits | `MCP_UPLOADS_PER_MIN`, `MCP_SEARCHES_PER_MIN`, `MCP_GENERATIONS_PER_MIN`, `MCP_IMPORTS_PER_MIN`, `SYNC_INGESTS_PER_MIN`, `PREVIEW_RENDERS_PER_MIN`, `SYNC_FREEZE_MS` | Defaults sized for the hosted service; requests over a cap get `429` |
  606. | Webhooks | `WEBHOOK_ALLOW_PRIVATE_URLS` ([webhooks](docs/webhooks.md)) | Webhook URLs on private networks are refused |
  607. | Analytics | `VITE_POSTHOG_KEY` (build time: a Docker build `ARG`), `POSTHOG_KEY`, `POSTHOG_*_HOST` | No analytics; when set, the browser reports through the same-origin `/relay` proxy |
  608. | iOS push | `DOOP_APNS_TEAM_ID`, `DOOP_APNS_KEY_ID`, `DOOP_APNS_PRIVATE_KEY`, `DOOP_APNS_BUNDLE_ID` | No Live Activity pushes; the app polls |
  609. | Gemini cloud pilot | `DOOP_GEMINI_CLOUD_WORKERS` ([pilot guide](docs/gemini-cloud-pilot.md)) | Off |
  610. ## Connect an AI agent
  611. The MCP endpoint (streamable HTTP, stateless) is at:
  612. ```
  613. http://localhost:4300/mcp
  614. ```
  615. Claude Code:
  616. ```bash
  617. claude mcp add --transport http doop http://localhost:4300/mcp
  618. ```
  619. Codex:
  620. ```bash
  621. codex mcp add doop --url http://localhost:4300/mcp
  622. codex mcp login doop # approve in the browser
  623. ```
  624. In the Doop desktop app, **Connect AI → Codex → Add to Codex** writes the entry into
  625. `~/.codex/config.toml` for you (CLI and the Codex tab of the ChatGPT desktop app). Connect AI also
  626. has one-click **Add to Claude** and **Add to Cursor**. ChatGPT needs Doop on a public HTTPS address
  627. (or an OpenAI Secure MCP Tunnel); it cannot reach `localhost`.
  628. Generic MCP config:
  629. ```json
  630. { "mcpServers": { "doop": { "type": "http", "url": "http://localhost:4300/mcp" } } }
  631. ```
  632. OpenCode takes Doop as a remote MCP server in `opencode.json`. An
  633. [agent key](#headless-agents-agent-keys) in the header skips the browser sign-in:
  634. ```json
  635. {
  636. "$schema": "https://opencode.ai/config.json",
  637. "mcp": {
  638. "doop": {
  639. "type": "remote",
  640. "url": "http://localhost:4300/mcp",
  641. "headers": { "Authorization": "Bearer dpk_…" }
  642. }
  643. }
  644. }
  645. ```
  646. ### Headless agents (agent keys)
  647. The OAuth flow above assumes a human at a browser to approve the connection. A headless client — a
  648. Mastra workflow, n8n, CI, any server-side agent framework — authenticates with an **agent key**
  649. instead: mint one under **Settings → Agent keys** and send it as a bearer header. The key acts as
  650. your account (same canvas access, same attribution) and is checked on every request, so revoking it
  651. in Settings cuts the agent off immediately.
  652. ```json
  653. {
  654. "mcpServers": {
  655. "doop": {
  656. "type": "http",
  657. "url": "http://localhost:4300/mcp",
  658. "headers": { "Authorization": "Bearer dpk_…" }
  659. }
  660. }
  661. }
  662. ```
  663. Then tell the agent something like:
  664. > Work on canvas `<canvas-id>` (shown in the top bar). Call `get_canvas` to see the existing frames.
  665. > To design, create a frame with `create_frame`, then stream the design into it with `append_frame_html`
  666. > one complete section at a time, roughly 1–4 KB per chunk (`start=true` on the first, `done=true` on the last) so people watch it
  667. > build up live. Complete HTML with inline CSS. After finishing, call `get_frame_screenshot` to see it,
  668. > fix what looks wrong, and re-check. Pick an `agent_name` and reuse it on every call.
  669. Screenshots render in your system Chrome/Chromium via `puppeteer-core` (set `CHROME_PATH` if it isn't
  670. auto-detected). Humans can hit the same renderer at `GET /api/frames/:id/screenshot.png?scale=2`.
  671. For website viewing/imports, setting `CONTEXT_DEV_API_KEY` makes Context.dev acquire the rendered
  672. HTML while Doop still sanitizes it and renders the preview locally; without the key, Doop navigates
  673. to the public page directly in Chromium.
  674. ### Design sync: push an app's live screens onto a canvas
  675. Server-side import can't reach apps behind SSO or a VPN. The **doop-sync snippet** flips the capture
  676. to the user's browser: mint a write-only key under a canvas's **Import → Live app**, drop one tag into the app —
  677. ```html
  678. <script async src="https://your-doop-origin/doop-sync.js?key=dk_…"></script>
  679. ```
  680. — and every distinct screen people visit lands on that canvas as a frame (one row per app), imported
  681. once: a grace window (`SYNC_FREEZE_MS`, 15 minutes by default) lets the first capture settle (scroll reveals, late images), then the frame
  682. freezes so later visits — different viewports, other users' data, open menus — never churn it. Deleting
  683. a frame re-imports it on the next visit; navigation counts keep accumulating regardless. Routes are
  684. normalized (`/orders/8231` → `/orders/:id`) so each screen maps to one
  685. frame; captures are serialized from the CSSOM (so styled-components/emotion output survives), and
  686. same-origin webfonts and small images are inlined as data: URIs — fonts require CORS inside the
  687. sandboxed frame, and intranet URLs would never render for viewers outside the network. Scripts are
  688. stripped client- and server-side, input values are always dropped, and anything marked `data-doop-mask`
  689. is redacted before upload (`data-doop-sync-ignore` excludes an element entirely). The key is the whole
  690. credential: it can only write frames to its one canvas, so revoking it under Import → Live app cuts the
  691. app off instantly. Endpoint: `POST /ingest/<key>` (CORS-open, no cookies).
  692. ### How streaming looks (server-side smoothing)
  693. Agent HTML lands in the store immediately, but viewers see it through a **typewriter reveal**: the server
  694. broadcasts the accumulated HTML in 80 ms ticks at about 8,000 chars/s, with every reveal lasting between
  695. 2.5 s and 5 s,
  696. so even an agent that sends few large chunks — or a one-shot `set_frame_html` / `create_frame` with
  697. full HTML — plays back as a smooth live stream. Mid-reveal HTML is _healed_ before broadcast: a trailing
  698. half-written tag is dropped, an unclosed `<script>` is cut (never run half-written JS), and an unclosed
  699. `<style>` is closed so content paints instead of blanking. Human edits from the inspector bypass the
  700. reveal (and a human html edit cancels any open reveal — the human takes over).
  701. While a stream/reveal is open the frame gets a pulsing dashed border and a "✦ <agent> is designing…"
  702. chip; "finished designing" logs when the reveal completes. A stale stream auto-closes after 30s.
  703. There is also a REST equivalent: `POST /api/frames/:id/append` with `{ html_chunk, start?, done? }`;
  704. the author is always the signed-in user.
  705. ### How agents learn the workflow
  706. Steering happens at three layers (the same architecture paper.design uses, plus result nudges):
  707. 1. **Server `instructions`** at MCP initialize — a compact contract: load the guide, get context
  708. first, stream designs, review with screenshots, keep one `agent_name`.
  709. 2. **`get_guide` tool** — the deep playbook (mandatory review checkpoints, streaming workflow,
  710. frame sizing, design-quality doctrine, multiplayer etiquette), loaded once per session and
  711. re-loadable after context compaction. Source: `server/guide.ts`.
  712. 3. **Result nudges** — `create_frame` / `set_frame_html` / final `append_frame_html` results tell
  713. the agent it hasn't _seen_ its design yet and to call `get_frame_screenshot` before moving on.
  714. Other results remind an agent to read canvas style guides it hasn't opened, to announce itself
  715. with `set_status`, and point out HTML that arrived escaped; open human feedback rides along too.
  716. `get_guide` has one topic, `doop-instructions`, covering human feedback, the design brief, images,
  717. style guides and memory, redesigns, prototypes and exporting; extensions such as Linear add their
  718. own lines. The built-in Doop Agent gets the same text in its system prompt and most of the same
  719. tools; `tests/agentToolParity.test.ts` lists the MCP tools it does not have yet.
  720. ### MCP tools
  721. 42 tools: 40 built in ([`server/mcp.ts`](server/mcp.ts)) plus the two Linear tools its extension
  722. registers ([`server/linear/extension.ts`](server/linear/extension.ts)). Every tool carries
  723. read-only / destructive / idempotent annotations; the server registers no MCP prompts.
  724. | Tool | What it does |
  725. | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
  726. | `get_guide` | The agent playbook — agents are instructed to load this first |
  727. | `set_status` | Broadcast a one-line "what I'm working on" — shown live in the working-now strip, avatar tooltip, and activity feed |
  728. | `get_profile` | The Doop account this connection is signed in as |
  729. | **Canvases** | |
  730. | `list_canvases` | List the canvases you can open, including workspace canvases |
  731. | `create_canvas` | Create a canvas (optionally in a workspace), returns its shareable id |
  732. | `get_canvas` | Canvas layout: every frame's position/size/meta |
  733. | `set_canvas_pages` | Create, rename, reorder or delete canvas pages |
  734. | `set_page_background` | Paint one page's canvas a colour of its own, or clear it back to the theme paper |
  735. | **Frames** | |
  736. | `create_frame` | Add a frame with HTML (auto-placed if no x/y) |
  737. | `get_frame` | Read a frame including its HTML |
  738. | `append_frame_html` | **Stream** a design in chunks (`start=true` first, `done=true` last) — viewers watch it build up |
  739. | `set_frame_html` | Replace a frame's design in one shot — renders live for everyone |
  740. | `edit_frame_html` | Targeted exact find/replace in a frame's HTML — morphs into the render in place |
  741. | `update_frame` | Rename / move / resize a frame |
  742. | `delete_frame` | Remove a frame |
  743. | `list_frame_versions` | Earlier states of a frame, newest first, with author and time |
  744. | `restore_frame_version` | Put a frame back to an earlier state; the replaced design is kept as a version |
  745. | `get_frame_screenshot` | Render the frame headlessly and return a PNG — lets agents _see_ and iterate on their design |
  746. | `export_frame` | PNG/JPG URLs that re-render when the design changes, or a vector PDF |
  747. | **Prototypes** | |
  748. | `get_prototype` | Each page's flow start and every interaction (trigger, action, target), flagging links to missing frames |
  749. | `set_prototype_start` | Choose the frame a page's clickable prototype starts on |
  750. | **Collaboration** | |
  751. | `get_feedback` | Fetch & claim open human feedback requests — for agents whose job is to poll the canvas periodically |
  752. | `get_comments` | Read element and canvas comments with their replies, optionally filtered by frame or resolution state, no claiming |
  753. | `reply_to_comment` | Reply inside an element-comment thread; `@mention` of a resident role is metered like a browser comment |
  754. | `resolve_comment` | Resolve an element-comment thread; resolving an `@mention` thread records the exchange in canvas Memory |
  755. | `report_issue` | Report a tool failure or missing capability to the instance admins |
  756. | `share_feedback` | Share suggestions and feedback with the instance admins |
  757. | **Design memory** | |
  758. | `list_guidelines` | List a canvas's style guides (brand rules, style recipes) with one-line summaries |
  759. | `get_guidelines` | Read one style guide in full — the rules every frame on the canvas must follow |
  760. | `set_guidelines` | Write or revise a style guide (versioned, with history) |
  761. | `get_reference` | Read a frame a human pinned as a "more like this" style reference |
  762. | `save_decision` | Record a design decision so later agents don't re-litigate it; feeds the distiller |
  763. | **Assets & inspiration** | |
  764. | `search_images` | Stock photo search (Pexels) — returns thumbnails the agent picks from |
  765. | `search_icons` | 200,000+ open-source icons (Iconify) as hotlinkable SVGs |
  766. | `search_logos` | Real company logos by brand name or domain (Brandfetch, vector marks) |
  767. | `list_backgrounds` | Curated hero/section/bento backgrounds (glows, grainy meshes, aurora, painterly) as thumbnails |
  768. | `search_inspiration` | Curated live landing pages with style, colour, fonts and sections (One Page Love) |
  769. | `generate_image` | Generate an image with the model the user picked in Settings (GPT Image, Nano Banana or Seedream) → asset URL |
  770. | `upload_asset` | Store your own file — from a URL, a one-time local-file upload URL, or inline base64 |
  771. | **Web** | |
  772. | `view_website` | Inspect one public page read-only; returns a desktop screenshot and visible text without changing the canvas |
  773. | `import_webpage` | Import one public URL onto a canvas as an editable HTML snapshot/frame |
  774. | **Linear** | |
  775. | `list_linear_issues` | List tickets through the user's Linear connection (open, most recently updated first) |
  776. | `get_linear_issue` | Read a Linear ticket and its description by UUID or identifier |
  777. Mutating tools accept `agent_name`; the agent then appears in the presence stack (pulsing square avatar),
  778. gets an "editing" ring + chip on the frame it touched, and its actions land in the activity feed. Agents
  779. expire from presence after ~20s of inactivity (~60s while they have a posted status, since a status
  780. usually means the agent is thinking between tool calls).
  781. Agent-to-human ownership comes from the OAuth token: the bearer token identifies who approved
  782. the connection, and that user shows up as the agent's owner in tasks and presence.
  783. ### Live task narration
  784. Agents are steered (instructions + guide) to call `set_status` with a one-line, present-tense summary
  785. when they start a task and whenever their focus shifts — e.g. _"Sketching a mobile onboarding flow"_.
  786. Statuses appear in a floating **working-now strip** at the top-left of the canvas, beside the tool rail
  787. (at the bottom on phones; on screens 1180px and wider the top-bar presence pill shows them instead), in
  788. the presence avatar tooltip, and as an activity feed entry, so you always know what
  789. each agent is doing even while it's silently thinking. An empty string clears the status; it also
  790. expires with the agent's presence.
  791. Every status also becomes a **task**: posting a new status completes the previous one, clearing (or
  792. going silent) ends the open task. Agents that never call `set_status` still show up: the server
  793. infers a task from what they visibly do (_"Designing 'Hero'"_, italicized in the panel), closes it
  794. when the stream finishes, and nudges them in tool results to start announcing — so the panel works
  795. even for sessions that connected before the tool existed or skipped the guide. The **Agents** tab of
  796. the side panel shows the history per agent (active task pulsing with a running duration, finished
  797. ones checked off with how long they took, failed cards with **Retry**), Cursor-agent-panel style,
  798. above the composer that queues new cards (with a model and effort picker and image attachments);
  799. **Activity** is the raw event feed. Task history survives agents leaving and is sent to late joiners.
  800. ### Steering agents: feedback on tasks
  801. In the app, people steer agents with [comments](#comments-imports-and-exports): `@mention` a role
  802. on the element in question. For scripts and integrations, `POST /api/tasks/:id/feedback` with
  803. `{ text }` leaves a note on a task (the signed-in user is the author; it counts as one Doop Agent
  804. task, so it can return `403 resident_limit`).
  805. Each note becomes an **open request on the canvas** — a work item, not mail for the agent whose
  806. task it was. MCP is pull-based, so delivery rides the result-nudge layer: the **next identified
  807. agent call** on the canvas that supports feedback delivery (carrying an `agent_name`, whoever it is) returns a
  808. `HUMAN FEEDBACK` block quoting the note, saying whose work it concerns, and instructing the agent
  809. to address it before continuing — including editing another agent's frame (a human request
  810. overrides the don't-touch etiquette). Each note is claimed exactly once.
  811. Agents don't linger waiting for replies — sessions end when their work ends. Open requests simply
  812. wait for the next agent to show up: the original agent in a later session, a different agent
  813. already on the canvas, or a fresh one you spawn (_"check in on canvas ⟨id⟩"_). For a dedicated
  814. caretaker, point an agent at `get_feedback` — a non-blocking fetch-and-claim designed for a
  815. "check the canvas every few minutes, address whatever humans requested" loop.
  816. ### Element comments through MCP
  817. Call `get_comments({ canvas_id })` to read the canvas's retained element comments and replies
  818. (up to 100 entries, newest first). Each entry includes its ID, frame ID, author, text, timestamp,
  819. CSS selector, HTML snippet, and any claim, failure, or resolution metadata. Replies carry a
  820. `parentId` pointing to their root comment.
  821. Pass `frame_id` to read only comments on a frame belonging to that canvas, or
  822. `include_resolved: false` to exclude resolved entries. Resolved entries are included by default
  823. so conversation context remains available. An empty result is `[]`. The tool enforces the same
  824. canvas access permissions as other MCP reads; optional `agent_name` announces presence.
  825. It does not claim task feedback or comments, or mark anything resolved.
  826. `reply_to_comment({ canvas_id, comment_id, text, agent_name })` adds a reply to a thread,
  827. inheriting the root's element anchor. `resolve_comment({ canvas_id, comment_id, agent_name })`
  828. closes it, and resolving an `@mention` thread also records the exchange in canvas Memory. Both
  829. require the same canvas access as every other MCP tool. A reply whose text `@mentions` a resident
  830. role spends one resident task from the account's allowance — the same free-tier meter that a board
  831. card, an `@mention` comment, or task feedback consumes (`server/allowance.ts`); plain replies are
  832. free. `resolve_comment` also costs nothing.
  833. ## Automations
  834. An automation runs on a schedule (daily, weekdays or weekly, in any time zone) or
  835. when designs on a selected canvas are approved. Configure up to six steps at `/automations`.
  836. Approval presets make different sizes, localize designs, or create companion assets;
  837. edit the brief to choose dimensions, languages and deliverables. Generated designs start as drafts.
  838. - **Pull steps** land designs on a canvas: **Meta ad creatives** (up to 200 ads, each with its image,
  839. name, copy and CTA; `META_APP_ID`/`_SECRET`, read-only `ads_read` scope).
  840. - **Agent steps** queue a board card for one Doop Agent role, identical to a card a person writes,
  841. and billed to the automation's owner. Following steps wait until that card completes.
  842. - **Create Linear ticket** uses the owner's connected Linear account and selected team.
  843. The connection needs permission to create issues.
  844. - **Post to Slack** uses the owner's Slack installation and a channel ID. Invite @Doop
  845. to the destination channel. Both handoff actions include source design links and links
  846. produced by earlier steps.
  847. Schedules are checked every minute; approvals and ongoing work every five seconds. One run
  848. per automation is active at a time. Up to ten approvals are grouped into each run, with each
  849. approval processed once, including after a restart or run-history cleanup. Enabling a workflow
  850. watches future approvals; **Run now** also picks up existing, unprocessed approvals.
  851. Changing an approved source to draft or needs review stops its remaining workflow steps.
  852. Agent work times out after one hour. Sizes, languages, and asset briefs are editable presets.
  853. Every run has a summary or an actionable error. Interrupted external calls fail visibly instead
  854. of automatically repeating a possibly successful ticket or message. Check the destination before
  855. reapproving a design to start another run. Approval receipts are retained until the automation is
  856. deleted; completed run history is limited to 100 entries. Existing scheduled automations retain
  857. their schedules and now wait for agent completion between steps.
  858. Types live in [`shared/automations.ts`](shared/automations.ts), the runner in
  859. [`server/automations.ts`](server/automations.ts).
  860. ## What's in the box
  861. - **Infinite canvas and editor** — tools, frames, elements, layers, rulers and shortcuts are in
  862. [The canvas editor](#the-canvas-editor).
  863. - **Multiplayer** — live cursors with name tags, presence avatars, follow mode, per-frame "who's
  864. editing" indicators, colored flash when a remote actor changes a frame, drag positions streamed
  865. live, a "Reconnecting / saved" status, auto-reconnect.
  866. - **Activity feed** — every create/edit/rename/delete, by whom (user or agent), with timestamps.
  867. - **Sharing** — invites, link levels (view / comment / edit), workspaces and the Community gallery
  868. from the **Share** modal ([Accounts](#accounts)).
  869. - **Connect AI modal** — one-click installs for Claude, Cursor and Codex, plus copy-paste setup for
  870. every other MCP client.
  871. - **Home** — a prompt that turns into a canvas with drafts queued (choose drafts per prompt, attach a
  872. design to start from), your canvases in a grid or list with sorting and owner filters, a
  873. self-ticking getting-started checklist, and the ⌘K search palette.
  874. - **Desktop app** — macOS and Windows ([`desktop/`](desktop/README.md)): canvas tabs, a native View
  875. menu, Check for Updates, one-click agent installs and `doop://` links that hand sign-in and
  876. integration OAuth back from the browser.
  877. ## REST API
  878. The web app talks to the same REST API you can script against. It authenticates with the
  879. better-auth session cookie (agents use [MCP](#connect-an-ai-agent) instead), and every route
  880. applies the same canvas access rules. Route handlers live in
  881. [`server/index.ts`](server/index.ts) plus the routers it mounts.
  882. | Prefix | What it covers |
  883. | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
  884. | `/api/canvases` | Canvases and their members, pages, flow start, guides, guidelines, references, cards, comments, imports, sync keys, assets, `export.pdf` |
  885. | `/api/frames` | Frames: edit, stream (`/append`), versions and restore, approval, comments, `screenshot.png` |
  886. | `/api/comments`, `/api/tasks`, `/api/feedback` | Replies, resolve and retry; task feedback |
  887. | `/api/workspaces`, `/api/billing` | Workspaces, people, roles, Stripe checkout |
  888. | `/api/automations`, `/api/integrations`, `/api/webhooks` | Automations, connected tools, outbound webhooks |
  889. | `/api/model-account`, `/api/image-model`, `/api/agent-keys` | Model accounts and their catalogs, the image model, agent keys |
  890. | `/api/community`, `/api/admin`, `/api/notifications` | The gallery, instance admin, comment-email preferences |
  891. | `/i/<frameId>.png`, `/a/<id>.<ext>`, `/u/<token>` | Public live frame images, stored assets, single-use upload tickets (15 minutes, 5 MB) |
  892. | `/ingest/<key>`, `/stripe/webhook`, `/healthz` | Design-sync captures, Stripe events, health check |
  893. The realtime protocol is plain JSON over `/ws`, one room per canvas; its message types are in
  894. [`shared/types.ts`](shared/types.ts).
  895. ## Architecture
  896. The main entry points (the server has about 70 modules in all):
  897. ```
  898. server/ Node (tsx) — one process on :4400
  899. index.ts Express REST API + ws rooms + presence + static serving (prod)
  900. store.ts In-memory canvas/frame state (hot path), write-through to the DB
  901. db/ Drizzle schema + PGlite/Postgres connection + migrations
  902. actions.ts Shared mutations: broadcast + activity log + agent presence + streaming reveal
  903. mcp.ts MCP server (@modelcontextprotocol/sdk), stateless streamable HTTP at /mcp
  904. guide.ts The agent guide (get_guide) and the shared prototype/design doctrine
  905. resident.ts The built-in Doop Agent; agentModel.ts picks the credential a run uses
  906. auth.ts better-auth: email/password, SSO, Google/Microsoft/Apple, MCP OAuth
  907. automations.ts Scheduled and approval-triggered workflows
  908. extensions.ts Registry for the Linear and Slack integrations (server/linear, server/slack)
  909. seed.ts Demo canvas on first run
  910. shared/ Types and logic shared by server and client (ws protocol, prototypes, pages)
  911. src/ React + Vite + zustand client on :4300
  912. pages/ Route-level screens (Home, CanvasPage, Settings, Automations…)
  913. components/ Canvas editor and app UI; components/ui/ holds every styled primitive
  914. styles.css Design tokens, the base reset, and keyframes. Nothing else.
  915. desktop/ Tauri desktop app (macOS, Windows)
  916. ios/ SwiftUI iPhone and iPad app
  917. claude-extension/ Claude Desktop extension (.mcpb); cursor-plugin/ and chatgpt-plugin/ beside it
  918. public/doop-sync.js The design-sync snippet
  919. ```
  920. ### Styling
  921. Doop's look is a component system, not a stylesheet. `src/components/ui/` holds the
  922. primitives — `Button`, `Input`, `Badge`, `Card`, `Panel`, `Modal`, `Menu`, `Toolbar`,
  923. `Segmented`, `Dash*` and the rest — each a Tailwind + [CVA](https://cva.style) recipe bound
  924. to the tokens in `styles.css`. Screens compose those; they don't re-describe borders,
  925. shadows or type scales. If a pattern shows up twice, it belongs in `ui/`.
  926. `src/styles.css` is deliberately small: the `:root` tokens (`--ink`, `--paper`, `--brand`…),
  927. their `@theme inline` mapping onto Tailwind names, the base reset, and the `@keyframes`
  928. utilities cannot express. Components reference those animations by name, so the names are
  929. API. `--breakpoint-md` (900px) is the mobile boundary and `useIsMobile()` matches it in JS —
  930. change them together.
  931. Frame HTML renders in `<iframe sandbox="allow-scripts">` — scripts run, but no same-origin access and
  932. no reach into the app. Each iframe loads a small bootstrap once; new HTML is `postMessage`d in and
  933. **DOM-morphed in place** (`src/lib/frameRuntime.ts`), so updates and streaming ticks never white-flash
  934. the frame with a full document reload. Changed `<script>`s re-execute; unchanged styles/fonts are
  935. untouched. The realtime layer is plain JSON over a per-canvas WebSocket room;
  936. REST/MCP mutations are broadcast to the room by the shared actions layer, so human and agent edits go
  937. through identical plumbing.
  938. ## Contributing
  939. PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for commit conventions and code style. First-time
  940. contributors sign the [CLA](CLA.md); a bot asks for it on your first PR.
  941. | Command | What it does |
  942. | --------------------------------- | --------------------------------------------------------------------------------- |
  943. | `bun run test` | Vitest over `tests/`: unit tests plus integration tests that boot the real server |
  944. | `bun run typecheck` | `tsgo`, the native TypeScript compiler |
  945. | `bun run lint` / `bun run format` | oxlint + ESLint / Prettier |
  946. | `bun run doc-lint` | Checks that `CLAUDE.md` and `.context/` stay in step with the code |
  947. | `bun run storybook` | The component catalogue on :6006 |
  948. CI runs all of these except Storybook, plus `format:check` and a production build, on every PR, and lints the PR title as a conventional
  949. commit (PRs land as a squash). Schema changes go through drizzle migrations (`npx drizzle-kit generate`
  950. after editing `server/db/schema.ts`). Security issues: see [SECURITY.md](SECURITY.md) — please report
  951. privately.
  952. ## License
  953. Doop is open source under the [GNU AGPL v3](LICENSE). In short: use it, self-host it,
  954. modify it — but if you offer a modified version as a service, you must publish your
  955. changes under the same license.
  956. The **doop name and logo are trademarks** and are not covered by the code license —
  957. please rebrand derived services.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.