Doop: a design canvas where you and your agents work side by side.

O que é o DoopWhat Doop is

O Doop é uma alternativa de código aberto ao Paper.design: uma tela de design multiusuário onde pessoas e agentes de IA desenham juntos, em tempo real. Cada design vive numa tela compartilhável (/c/<id>) feita de frames que renderizam HTML dentro de iframes isolados. Pessoas editam no navegador; agentes editam por um servidor MCP embutido. A licença é AGPL-3.0; o nome e o logo são marcas registradas e a licença não os cobre.Doop is an open-source alternative to Paper.design: a multiplayer design canvas where people and AI agents design together in real time. Each design lives on a shareable canvas (/c/<id>) made of frames that render HTML inside sandboxed iframes. People edit in the browser; agents edit through a built-in MCP server. The license is AGPL-3.0; the name and logo are trademarks and the license does not cover them.

Como ele é por dentroHow it works inside

O repositório separa o servidor, o cliente e o código compartilhado. Isso importa na hora de hospedar: em produção é um único processo Node na porta 4400 que serve a API, o WebSocket, o MCP e o cliente já compilado.The repository splits the server, the client and the shared code. That matters when hosting: in production it is a single Node process on port 4400 that serves the API, the WebSocket, the MCP and the built client.

Stack: Bun (instalar e compilar), Node (rodar o servidor), TypeScript, Express, ws, Drizzle ORM, PGlite (Postgres embutido) ou Postgres, better-auth, React, Tailwind e Vitest. Cada frame é um iframe com sandbox="allow-scripts", atualizado por “morph” do DOM em vez de recarregar. As imagens dos frames vêm do puppeteer-core dirigindo o Chrome ou Chromium do sistema.Stack: Bun (install and build), Node (server runtime), TypeScript, Express, ws, Drizzle ORM, PGlite (embedded Postgres) or Postgres, better-auth, React, Tailwind and Vitest. Each frame is an iframe with sandbox="allow-scripts", updated by DOM morphing instead of reloading. Frame screenshots come from puppeteer-core driving the system Chrome or Chromium.

Rodar no seu computadorRun it on your computer

Requisitos: Bun (instala e compila), Node no PATH (o bun run dev e o bun run build também empacotam a extensão do Claude Desktop com Node) e Chrome ou Chromium para os screenshots (detectado sozinho, ou defina CHROME_PATH).Requirements: Bun (install and build), Node on your PATH (bun run dev and bun run build also package the Claude Desktop extension with Node) and Chrome or Chromium for screenshots (auto-detected, or set CHROME_PATH).

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

Abra http://localhost:4300 (o app). A API, o WebSocket e o MCP ficam em http://localhost:4400. Não precisa de configuração: os dados vão para um Postgres embutido (PGlite) em data/pg. Apague essa pasta para zerar tudo.Open http://localhost:4300 (the app). The API, WebSocket and MCP are on http://localhost:4400. No configuration is needed: data goes to an embedded Postgres (PGlite) in data/pg. Delete that folder to reset everything.

Para testar o build de produção sem Docker, num único processo:To try the production build without Docker, as a single process:

bun run build && bun run start
# tudo em http://localhost:4400
# com um Postgres de verdade: DATABASE_URL=postgres://usuario:senha@host:5432/doop bun run start

Rodar com DockerRun it with Docker

O Compose do projeto sobe o app e um Postgres, na porta 4400. O BETTER_AUTH_SECRET assina as sessões: gere um valor longo e aleatório e guarde-o, porque trocá-lo derruba os logins.The project Compose file starts the app and a Postgres on port 4400. BETTER_AUTH_SECRET signs sessions: generate a long random value and keep it, because changing it logs everyone out.

BETTER_AUTH_SECRET=$(openssl rand -hex 32) docker compose up -d

Para só conferir a imagem de produção na sua máquina:To just check the production image on your machine:

docker build -t doop .
docker run -p 4400:4400 \
  -e BETTER_AUTH_URL=http://localhost:4400 \
  -e BETTER_AUTH_SECRET=dev-only doop

Rodar numa nuvemRun it in a cloud

O Dockerfile de produção já inclui o cliente compilado e o Chromium. A documentação indica o Railway e o Fly como o caminho de menor atrito, mas qualquer lugar que rode um contêiner serve (uma VPS com Docker Compose, ECS, Cloud Run).The production Dockerfile already bundles the built client and Chromium. The documentation names Railway and Fly as the least-friction path, but anywhere that runs a container works (a VPS with Docker Compose, ECS, Cloud Run).

1. Crie o app a partir do repositório. As duas plataformas detectam o Dockerfile sozinhas.Create the app from the repository. Both platforms detect the Dockerfile on their own.
2. Adicione um Postgres gerenciado e defina DATABASE_URL. O PGlite é de um processo só: só serve para uma instância com um volume persistente em /app/data.Add a managed Postgres and set DATABASE_URL. PGlite is single-process: it only suits one instance with a persistent volume at /app/data.
3. Defina BETTER_AUTH_SECRET (string longa e aleatória, obrigatória em produção) e BETTER_AUTH_URL (a origem pública, como https://doop.exemplo.com, também obrigatória). Use TRUSTED_ORIGINS para outras origens permitidas.Set BETTER_AUTH_SECRET (a long random string, required in production) and BETTER_AUTH_URL (the public origin, such as https://doop.example.com, also required). Use TRUSTED_ORIGINS for any other allowed origins.
4. Use GET /healthz como health check. O servidor confia em um salto de proxy, então terminar o TLS na borda da plataforma funciona.Use GET /healthz as the health check. The server trusts one proxy hop, so terminating TLS at the platform edge works.
5. Se quiser, defina um SMTP, o armazenamento S3 e os logins sociais (próxima seção).Optionally set SMTP, S3 storage and social sign-in (next section).

Exemplo numa VPS qualquer, com Postgres no mesmo Compose e HTTPS na frente (Caddy ou Cloudflare Tunnel, que não precisam de portas abertas além da 443):Example on any VPS, with Postgres in the same Compose and HTTPS in front (Caddy or a Cloudflare Tunnel, which need no ports open besides 443):

# no servidor, dentro de uma cópia do repositório
cat > .env <<EOF
BETTER_AUTH_SECRET=$(openssl rand -hex 32)
BETTER_AUTH_URL=https://doop.exemplo.com
EOF
docker compose up -d
curl -fsS http://127.0.0.1:4400/healthz   # health check
# coloque o proxy HTTPS na frente da porta 4400

Variáveis de ambiente que importamEnvironment variables that matter

O arquivo .env.example do repositório lista o conjunto completo (endpoints, chaves de geração de imagem e busca, limites de taxa).The repository .env.example lists the full set (endpoint overrides, image generation and search keys, rate limits).

Conectar agentes de IAConnecting AI agents

O endpoint MCP é /mcp. Em desenvolvimento, http://localhost:4300/mcp; em produção, a sua origem pública mais /mcp.The MCP endpoint is /mcp. In development, http://localhost:4300/mcp; in production, your public origin plus /mcp.

# Claude Code (login pelo navegador, OAuth)
claude mcp add --transport http doop http://localhost:4300/mcp

# Codex
codex mcp add doop --url http://localhost:4300/mcp
codex mcp login doop

Configuração genérica para qualquer cliente MCP:Generic configuration for any MCP client:

{ "mcpServers": { "doop": { "type": "http", "url": "http://localhost:4300/mcp" } } }

Para agentes sem navegador (CI, servidores), crie uma chave de agente em Configurações → Agent keys e envie-a como cabeçalho Authorization: Bearer. Ela dispensa o login e, ao ser revogada, corta o acesso na hora. Use uma chave por agente. O Doop Agent embutido fica desligado até um usuário conectar uma conta de modelo ou o operador definir ANTHROPIC_API_KEY e um RESIDENT_TASK_LIMIT maior que 0; agentes ligados por MCP usam as próprias assinaturas.For agents without a browser (CI, servers), create an agent key under Settings → Agent keys and send it as an Authorization: Bearer header. It skips the sign-in and, once revoked, cuts access immediately. Use one key per agent. The built-in Doop Agent stays off until a user connects a model account or the operator sets ANTHROPIC_API_KEY and a RESIDENT_TASK_LIMIT above 0; agents connected over MCP use their own subscriptions.

Atualizar quando o projeto melhorarUpdating when the project improves

O Doop ainda é jovem (versão 0.x, lançamentos frequentes), então atualizar faz parte da rotina. O que eu vi no repositório em 2026-10-29: o ramo padrão é main; os lançamentos são tags vX.Y.Z geradas pelo release-please (a última do servidor era v0.10.0); o CHANGELOG.md lista cada versão; tags desktop-v… são só do app desktop; as mudanças entram por squash no main, e há dezenas de ramos feat/* e fix/* de trabalho em andamento.Doop is still young (0.x versions, frequent releases), so updating is part of the routine. What I saw in the repository on 2026-10-29: the default branch is main; releases are vX.Y.Z tags produced by release-please (the latest server one was v0.10.0); CHANGELOG.md lists every version; desktop-v… tags are the desktop app only; changes land as squashes on main, and there are dozens of work-in-progress feat/* and fix/* branches.

Se você só clonou, o jeito simples é fixar numa tag. Se pretende ter alterações suas, faça um fork e mantenha um ramo seu em cima da tag.If you only cloned, the simple way is to pin to a tag. If you plan to keep changes of your own, make a fork and keep a branch of yours on top of the tag.

Passo a passo (Docker Compose ou Bun)Step by step (Docker Compose or Bun)

cd doop
git fetch --tags origin
git tag -l 'v*' --sort=-v:refname | head -5     # as versões mais recentes / the newest versions
git log --oneline HEAD..origin/main | head -20  # o que mudou desde a sua versão / what changed

# 1) leia o CHANGELOG e o .env.example novo (v0.11.0 é só um exemplo: use a tag que aparecer acima) / read them (v0.11.0 is just an example: use the tag listed above)
git diff HEAD v0.11.0 -- CHANGELOG.md .env.example docker-compose.yml

# 2) faça backup ANTES (banco e arquivos)
docker compose exec db pg_dump -U doop doop > backup-$(date +%F).sql

# 3) troque para a tag nova (exemplo: v0.11.0)
git checkout v0.11.0

# 4a) Docker Compose: recompile a imagem e recrie
docker compose build --pull && docker compose up -d
# 4b) Bun, sem Docker
bun install && bun run build && bun run start

# 5) confira
curl -fsS http://127.0.0.1:4400/healthz

Para acompanhar o main em vez de uma tag, troque o passo 3 por git checkout main && git pull --ff-only. Se você tem commits seus numa cópia (fork), use git remote add upstream https://github.com/kgoedecke/doop, depois git fetch upstream --tags e git rebase v0.11.0 (ou git merge v0.11.0) no seu ramo.To follow main instead of a tag, replace step 3 with git checkout main && git pull --ff-only. If you have commits of your own in a copy (fork), use git remote add upstream https://github.com/kgoedecke/doop, then git fetch upstream --tags and git rebase v0.11.0 (or git merge v0.11.0) on your branch.

• Seus dados ficam fora do código. No Compose, o banco está no volume doop-pg e sobrevive ao docker compose up -d; não use down -v, que apaga o volume. Com PGlite, o dado está em data/pg (ou no volume em /app/data) e o git checkout não mexe nele.Your data lives outside the code. In Compose the database is in the doop-pg volume and survives docker compose up -d; do not use down -v, which deletes the volume. With PGlite the data is in data/pg (or the volume at /app/data) and git checkout does not touch it.
• Mudanças de esquema. O projeto usa migrações do Drizzle (pasta server/db). Eu não confirmei se elas rodam sozinhas ao iniciar; por isso o backup do passo 2 e a leitura do changelog antes de subir uma versão nova em produção.Schema changes. The project uses Drizzle migrations (the server/db folder). I did not confirm whether they run on their own at startup; hence the backup in step 2 and reading the changelog before putting a new version in production.
• Troque uma versão por vez quando houver muitas entre a sua e a nova, e teste primeiro numa cópia (outra porta, outro banco).Move one version at a time when there are many between yours and the new one, and test first on a copy (another port, another database).
• Voltar atrás: git checkout <tag-anterior>, recompile e, se o esquema mudou, restaure o backup (docker compose exec -T db psql -U doop doop < backup.sql num banco vazio).Rolling back: git checkout <previous-tag>, rebuild and, if the schema changed, restore the backup (docker compose exec -T db psql -U doop doop < backup.sql into an empty database).
• Avisos de nova versão: no GitHub, “Watch” → “Custom” → “Releases” no repositório, ou assine o feed https://github.com/kgoedecke/doop/releases.atom.New-version alerts: on GitHub, “Watch” → “Custom” → “Releases” on the repository, or subscribe to the feed https://github.com/kgoedecke/doop/releases.atom.

Cuidados antes de abrir para outras pessoasCare before opening it to other people

• Cadastro aberto por padrão. Sem SIGNUP_EMAIL_DOMAINS, qualquer pessoa que alcance o endereço cria uma conta. Restrinja por domínio, ou deixe o serviço atrás de VPN, Tailscale ou Cloudflare Access.Open signup by default. Without SIGNUP_EMAIL_DOMAINS, anyone who can reach the address creates an account. Restrict by domain, or keep the service behind a VPN, Tailscale or Cloudflare Access.
• Um agente com acesso à tela escreve HTML que roda. Os frames ficam em iframes com sandbox="allow-scripts", mas trate o conteúdo gerado por agentes como não confiável e não cole nele segredos.An agent with canvas access writes HTML that runs. Frames sit in iframes with sandbox="allow-scripts", but treat agent-generated content as untrusted and do not paste secrets into it.
• O servidor dirige um Chrome. CHROME_NO_SANDBOX existe para contêineres sem as permissões do sandbox; só o ligue se precisar e dentro de um contêiner sem privilégios.The server drives a Chrome. CHROME_NO_SANDBOX exists for containers without sandbox permissions; only turn it on if you must, and inside an unprivileged container.
• Backup. Faça backup do Postgres (pg_dump) e do armazenamento de arquivos (data/assets ou o bucket S3).Backup. Back up Postgres (pg_dump) and file storage (data/assets or the S3 bucket).
• AGPL-3.0. Se você modificar o Doop e oferecê-lo a outras pessoas pela rede, precisa disponibilizar o código modificado a elas. As marcas “doop” e o logo não vêm com a licença.AGPL-3.0. If you modify Doop and offer it to other people over a network, you must make the modified source available to them. The “doop” name and logo do not come with the license.

Cola e revisãoCheat sheet and review

ColaCheat sheet

Perguntas de revisãoReview questions

• Por que o Doop usa duas portas no desenvolvimento e uma só em produção?Why does Doop use two ports in development and only one in production?
• Quando o PGlite basta e quando você precisa de um Postgres gerenciado?When is PGlite enough and when do you need a managed Postgres?
• Quais duas variáveis são obrigatórias em produção, e por quê?Which two variables are required in production, and why?
• Qual a diferença entre o login por OAuth e uma chave de agente?What is the difference between OAuth sign-in and an agent key?
• Qual ramo ou tag você seguiria em produção, e o que fazer antes de atualizar?Which branch or tag would you follow in production, and what do you do before updating?