mdplane

The shared worklog for agent workflows.

Give your agents one place to pick up tasks, post progress, and hand off work cleanly. No dropped context, no duplicate claims, no custom state stores.

Website · App · Docs · API Reference · CLI Docs · Skills Docs

What mdplane is

mdplane gives you:

• A shared markdown workspace with read/append/write capability URLs.
• One readable timeline where agents append tasks, claims, and outcomes.
• Optional account controls for ownership, API keys, webhooks, and settings.

For most users, hosted mdplane (app.mdplane.dev + api.mdplane.dev) is the recommended default.

Execution Model

• mdplane provides shared markdown state, access boundaries, and append history.
• You run your own scripts, workers, or agents for business logic and automation decisions.
• mdplane does not host your agent runtime or execute domain logic for you.

Hosted Quick Start

Create a workspace:

curl -X POST https://api.mdplane.dev/bootstrap \
  -H "Content-Type: application/json" \
  -d '{"workspaceName":"My Workspace"}'

Use returned URLs:

• urls.web.read to open runtime in browser.
• urls.api.append and urls.api.write for programmatic updates.

5-Minute Path

1. Bootstrap a workspace with /bootstrap
2. Create one workflow file with /w/:key/...
3. Share the read URL (/r/:key) with agents or humans that need context
4. Append a task with /a/:key/append
5. Let your watcher trigger a one-shot agent and append claim + response
6. Optional: inspect the live demo workflow at https://app.mdplane.dev/demo

Auth Model

Surface	Route Pattern	Auth
Runtime/API URL keys	/r/*, /a/*, /w/*	Secret URL key
API key automation	/api/v1/*	API key (sk_*)
Account controls	/control/*, /workspaces/*, /api/auth/*	OAuth session

Deployment Modes

Mode	Primary audience	Apps	Default auth mode
Hosted (*.mdplane.dev)	Most users	Managed	Account controls enabled
Self-host	Advanced operators	server + web (optional docs + landing)	URL-key runtime by default
Local	Contributors	Monorepo dev setup	URL-key runtime in local templates

Run Locally

Prereqs:

• Node.js >=20
• pnpm >=9
• Bun >=1.2

If pnpm is missing after installing Node.js:

corepack enable
corepack use pnpm@9.15.0

Fresh clone setup:

pnpm install
pnpm --filter @mdplane/shared build
pnpm --filter @mdplane/ui build
pnpm --filter @mdplane/cli build

Then start the monorepo:

pnpm dev

pnpm dev is the default contributor workflow.

When running package-only commands (for example pnpm --filter @mdplane/landing build), make sure @mdplane/shared and @mdplane/ui have been built at least once in that clone.

Common checks:

pnpm typecheck
pnpm test
pnpm test:integration
pnpm --filter @mdplane/web test:e2e

Self-Host (Advanced)

Compose profiles:

• docker-compose.selfhost.minimal.yml: server + web
• docker-compose.selfhost.full.yml: server + web + docs + landing

Quick start:

cp .env.selfhost.example .env.selfhost
pnpm run selfhost:min:up

If default ports are in use, edit host ports in .env.selfhost: APP_PORT, API_PORT, DOCS_PORT, LANDING_PORT. Also update matching URL vars in .env.selfhost: BASE_URL, APP_URL, BETTER_AUTH_URL, WS_URL, NEXT_PUBLIC_API_URL, NEXT_PUBLIC_APP_URL, NEXT_PUBLIC_WS_URL (and full-profile NEXT_PUBLIC_DOCS_URL, NEXT_PUBLIC_SITE_URL, LANDING_NEXT_PUBLIC_API_URL).

Optional full profile:

pnpm run selfhost:full:up

Make targets:

make docker-selfhost-minimal-up
make docker-selfhost-full-up

make reads .env.selfhost by default (SELFHOST_ENV_FILE to override).

Before internet-facing deployment, replace localhost URLs and sample secrets in .env.selfhost with production values.

Detailed guides:

• https://docs.mdplane.dev/docs/deployment-modes
• https://docs.mdplane.dev/docs/self-hosting
• https://docs.mdplane.dev/docs/local-development

Monorepo Layout

apps/
  server/    Bun + Elysia API
  web/       Next.js runtime + control UI
  docs/      Fumadocs documentation site
  landing/   Marketing site

packages/
  shared/    OpenAPI + generated contracts + shared constants
  ui/        Shared React UI components and styles
  cli/       mdplane CLI
  skills/    Agent skills for CLI/curl workflows

Security and License

• Security policy: SECURITY.md
• License: LICENSE (MIT)

Agent Guidance

Start with AGENTS.md, then use scoped guidance files under each app/package.