Shared HTML and Markdown planning, with revision history and AI access.
Keep diagrams, tables and interactive demos in one document, share a stable link, and let people and AI work against the same current version.
Developed for shared planning at Sundsvalls kommun, Sweden. The repository is maintained under the eneo-ai organization.
Early-stage software: suitable for evaluation by a trusted team. This is a single-workspace application with a Swedish interface, not a finished public document-hosting platform. Review the limitations and deployment guide before using it with sensitive information.
- Combines HTML and Markdown files on one planning card, preserving original sources, CSS and inline SVG.
- Stores immutable HTML revisions with a metadata snapshot; status, instructions and GitHub references can change without duplicating HTML.
- Rejects stale updates so concurrent work cannot silently overwrite newer content.
- Lets connected AI clients draw and refine native diagrams with Excalidraw; diagrams share content history and support zoom, fullscreen, text alternatives and PNG export.
- Provides comments, historical previews, restoration and original HTML/Markdown file export.
- Includes administrator, editor and viewer accounts, plus scoped personal API keys.
- Exposes REST with a public OpenAPI reference, and MCP for connected AI clients.
The stack is TypeScript, React/Next.js, PostgreSQL and Astryx components and design tokens. Astryx owns standard UI controls, navigation and dialogs; custom code composes the product and isolates the HTML preview. This is an explicit project rule in AGENTS.md. REST and MCP share one document owner rather than separate persistence implementations.
Requirements: Node.js 22, Docker with Compose v2, and Buildx 0.14 or later for the resource-limited startup script. Run commands from the repository root. The startup script does not require an npm installation on the host.
git clone https://github.com/eneo-ai/planroom.git
cd planroom
node scripts/configure.mjs
node scripts/start-local.mjsConfiguration creates .env with separate random database and initial admin passwords. It uses private file permissions on POSIX systems, never prints the passwords, and preserves an existing configuration. Read SEED_ADMIN_PASSWORD privately in .env to sign in. Windows users should also restrict that file's ACL. Manual configuration is available in .env.example.
Startup builds with a temporary builder limited to 2 GiB and one CPU, runs migrations and first-run seeding, then waits up to 90 seconds for container health. It removes the builder afterwards. The app and database remain running, with their own resource limits. Apply your host's required process supervisor when running this command; repository-specific requirements are recorded in AGENTS.md.
Open http://localhost:3210 and sign in as admin@planroom.local. Replace the initial name, email address and password before workspace access. The replacement password must have at least 12 characters. Then create individual colleague accounts in Settings.
A synthetic planning example is imported once when SEED_EXAMPLE=true. Restarts do not overwrite documents or reset the initial credentials. PostgreSQL uses a persistent named volume and has no published port. The app binds to 127.0.0.1 by default.
For ordinary Compose deployment, after configuration:
docker compose up --build -d
docker compose psThis direct command does not impose the startup script's build-memory limit; runtime container limits still apply. Use the startup script or your deployment system to bound build resources. See deployment and recovery for shared HTTPS access, upgrades and backups.
To stop without deleting data:
docker compose downImport one or more HTML/Markdown files, or create files and paste their sources, add instructions for continued work, and share the document link in your team chat. The recipient signs in to the same Planroom installation. A saved update includes a change summary and the document version it was based on. Only changed HTML creates a revision.
If someone saved first, reconcile the newer version before retrying. History stays intact, and restoration creates a new revision when HTML changes. Unsaved drafts survive navigation within the same browser tab, but disappear on reload or logout. Save changes for durable storage.
| Role | Workspace access |
|---|---|
| Viewer | Read documents, history and comments; create personal read keys |
| Editor | Viewer access plus document changes, restoration and comments; create read/write keys |
| Administrator | Editor access plus create individual user accounts |
All configured users can read all documents in this single workspace. A write key never grants more permission than its owner has.
Create a personal key under Settings → AI and API. Its secret is shown once and can be revoked there. Keys expire after 90 days; the settings page shows the exact date. Use a separate read key for each client unless it needs to write, and replace its key before expiry. The app also contains client-specific setup instructions for Codex, Claude Code and Claude Desktop.
| Interface | Local address | Authentication |
|---|---|---|
| MCP, Streamable HTTP | http://localhost:3210/api/mcp |
Authorization: Bearer <personal-key> |
| REST discovery | http://localhost:3210/api |
Public metadata |
| OpenAPI 3.1 | http://localhost:3210/api/openapi.json |
Public metadata |
| Interactive API reference | http://localhost:3210/api/docs |
Public page; bearer key for document requests |
The MCP server runs inside the app container. Claude Desktop can use the optional mcp-bridge Compose profile as a local stdio adapter. It exposes no port and receives a personal key from the client environment; it does not receive database credentials. The app must already be running. Use the product's copied configuration rather than placing a key in source code.
Cloud clients cannot reach your computer's localhost. They need a reachable HTTPS installation and a client that supports personal bearer authentication. OAuth is not implemented.
API-reference test requests reach the same installation, omit browser session cookies and keep keys in memory only. A write key can change real documents when you submit a request. Account and user administration require a browser session and should be performed through the workspace. Request and response details are in the API contract.
An AI should read the current document and its instructions before writing, and read again after a conflict. Imported instructions are untrusted project content, not permission to bypass authentication or other tool rules.
HTML and Markdown sources are stored without destructive sanitization and displayed in an isolated iframe, never the app's own DOM. CSS and SVG work without scripts. JavaScript is off by default and can be enabled explicitly for trusted demonstrations. The preview restricts external resources, forms and common network calls; it cannot guarantee that enabled scripts will not transmit data through frame navigation. Markdown supports headings, tables, checklists and code blocks; embedded HTML is shown as text and scripts stay disabled. Downloaded files preserve their original source; downloaded HTML no longer has Planroom's preview restrictions.
Use Expandera to view a plan in a fullscreen dialog and close it with the visible button or Escape. Display-mode changes reset temporary demo controls. Script approval applies to the current source and is discarded when that source changes.
The initial scope has no public document links, per-document ACLs, multiple workspaces, SSO, invitations, password-recovery email, account disabling/deletion, live collaborative editor or Mattermost bot. Document lists return the latest 200 matches. Do not use this as a tenant boundary between groups that must not read each other's documents.
Public metadata and health endpoints do not expose workspace content. Shared deployments require HTTPS and a correctly configured APP_URL. Revision history is not a backup. See SECURITY.md for the trust model and vulnerability reporting.
Five failed logins within ten minutes lock the email for ten minutes from the fifth failure. A correct password does not bypass an active lock. The app also bounds concurrent password work and has a shared 60-attempt/minute login budget. A shared budget can delay legitimate sign-in during abuse; use your proxy's connection and request limits as well.
Planroom is licensed under the MIT License. You can use, modify and redistribute the software, including commercially, while retaining the copyright and license notice. Contributions use the same license. The bundled example is synthetic; dependencies retain their own licenses.
Eneo uses AGPLv3. Planroom is a separate application with its own MIT license, not a distribution of Eneo's source code or assets.
Read CONTRIBUTING.md before changing behavior. It explains local checks, disposable PostgreSQL tests and contribution boundaries. CI checks types and behavior, audits all npm dependencies at every advisory severity, builds the Docker image and verifies startup. Actions and base images are pinned; Dependabot proposes weekly updates for review.
Useful documentation:
- Architecture and ownership
- REST contract
- Deployment, backups and recovery
- Validation record
- Security review and fixes
- Security policy
Copyright © 2026 Sundsvalls kommun and Planroom contributors. Distributed under the MIT License.
Open a plan's Visualisering tab, choose Visualisera med AI, describe the diagram and copy the assignment into a connected Codex or other MCP client with a write key. The AI reads the plan and draws native objects through read_canvas and apply_canvas_operations. The MCP visualize_plan prompt provides the same workflow. The diagram updates automatically in the active view; subsequent requests can refine individual objects. Original HTML/Markdown files stay intact and every changed batch is saved in content history. Frozen plans remain read-only. This uses your existing AI client; Planroom does not invoke a model internally.
The canvas stores bounded geometry and literal text, not arbitrary HTML. Use the text view, pan/zoom, fullscreen and PNG download to inspect or share a diagram. Files and diagrams restore together. SDK assets are self-hosted and Node.js 22.12.0 or later within Node 22 is required.
The embedded Excalidraw SDK is MIT-licensed and requires no production license key or subscription. Diagram fonts are served locally; see deployment. Planroom owns the saved diagram format and history independently of the SDK.