passage.md
A hosted Markdown workspace for humans and agents.
passage.md is a calm browser place to write Markdown, save it online, share it by URL, and let agents work with the same documents through raw Markdown, CLI, and API workflows.
It is not trying to be a local Markdown editor, a personal knowledge base, or a heavy team workspace.
The problem is file wrangling.
Local Markdown files are fine until the document needs to move between your laptop, your phone, another person, and an agent.
Visitors can read the public site and shared documents.
Signed-in Free accounts can save 5 hosted docs.
Pro users can save thousands of hosted docs, export and share them, and use CLI/API workflows.
Product
The product reference is Google Docs, Notion, and GitHub Gist, but stripped down to plain Markdown.
Google Docs is too rich for Markdown.
Notion is too heavy for a simple document.
GitHub Gists are useful, but they are developer plumbing, not a calm writing surface.
Passage is browser-first, URL-native Markdown.
The visual reference is calm minimalism without becoming a local-file writing app.
The technical wedge is agent usefulness without copy-paste, sync folders, or repo setup.
Every saved doc is plain Markdown, private by default, and addressable through web, MCP, and API.
Docs
GitHub Issues and project board 14 are the source of truth for roadmap, phase order, issue scope, acceptance criteria, dependencies, verification, and status.
Local docs are product and architecture notes only.
If local docs conflict with a GitHub issue, the GitHub issue wins.
Local Development
Prerequisites:
- Node.js 22 or newer.
- npm 10 or newer.
- Go 1.26 or newer.
- A native local PostgreSQL install, such as Postgres.app or Homebrew Postgres.
Install dependencies:
npm install
Create a local database:
createdb passage_dev
export DATABASE_URL='postgres://localhost:5432/passage_dev?sslmode=disable'
npm run dev uses that local database URL by default.
Run database migrations:
go run ./server/cmd/passage migrate
passage serve never applies migrations.
Run migrate before starting the app locally or deploying a new application revision.
npm run dev does this automatically.
Build the static web app and run the Go server:
export SESSION_SECRET='dev-session-secret-change-me'
npm run dev
The Go server runs at http://localhost:3000 by default and serves /api/health.
DATABASE_URL is required for serve; the dev command defaults it to postgres://localhost:5432/passage_dev?sslmode=disable.
PASSAGE_DATABASE_MAX_CONNS sets the per-process Postgres pool limit and defaults to 3.
PASSAGE_PUBLIC_SIGNUP_ENABLED gates public account creation and defaults to false.
SESSION_SECRET must be set explicitly when APP_ENV=production.
Copy .env.example to .env for local environment values.
Password reset links are logged by the Go server in local development when Resend is not configured.
To send real local email, set both RESEND_API_KEY and RESEND_FROM in .env.
Stripe billing is off by default.
Set STRIPE_BILLING_ENABLED=true only after STRIPE_SECRET_KEY, STRIPE_MONTHLY_PRICE_ID, STRIPE_WEBHOOK_SECRET, and APP_BASE_URL are configured.
Production Stripe account identifiers are not committed to the repository.
The deployment workflow reads the monthly price ID, Secret Manager names, and fixed secret versions from the matching GitHub repository variables only when an explicitly approved enable dispatch runs.
An explicit disable dispatch removes the Stripe price and secret bindings from the new Cloud Run revision.
Pull requests and pushes to main run CI and build the production image without publishing or deploying it.
Production deployment requires an explicit CI workflow dispatch from main and defaults to preserving the current billing state.
Abuse rate limits
The Go server applies fixed-window limits before handling auth mutations, authenticated document mutations, authenticated document searches, API-token requests, shared HTML, and raw Markdown.
Defaults are 20 auth mutations, 120 document mutations, 120 document searches, 30 API-token requests, 120 shared HTML requests, and 240 raw Markdown requests per minute.
Authenticated limits are keyed by user ID.
Public and auth limits are keyed by client IP.
Each class can be changed with the matching PASSAGE_RATE_LIMIT_<CLASS>_REQUESTS and PASSAGE_RATE_LIMIT_<CLASS>_WINDOW environment values shown in .env.example.
Set a request count to 0 to disable that class.
Production trusts X-Forwarded-For only when the immediate peer is in the configured PASSAGE_TRUSTED_PROXY_CIDRS.
It selects the client using PASSAGE_FORWARDED_HOPS, which defaults to the two proxy hops in the Cloud Run ingress path.
Local development trusts no forwarding headers.
Override both values together if the production proxy path changes.
With Postgres configured and writes enabled, counters are enforced atomically across Cloud Run instances and survive deploys and instance restarts.
Client IPs and user IDs are stored only as scoped HMAC digests.
Expired counters are removed through bounded, indexed cleanup batches.
Local development without Postgres uses process-local counters.
Database recovery mode also uses process-local counters so allowed reads remain database read-only while the outer write fence blocks mutations.
The existing Postgres-backed password-reset request and confirmation limits remain separate and unchanged.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
