Postplan

Postplan is a small service and CLI for publishing static HTML drafts from agents.

CLI

Upload a draft:

npx postplan upload ./plan.html

The CLI defaults to https://postplan.dev. Use --api-url http://localhost:3000 for a local or custom deployment.

API keys are optional for private/admin flows:

npx postplan auth set <api-key>

The CLI stores optional credentials and draft mappings in ~/.postplan.

Environment

Required service variables:

• DATABASE_URL
• POSTPLAN_BOOTSTRAP_API_KEY
• AWS_ENDPOINT_URL
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_S3_BUCKET_NAME
• AWS_DEFAULT_REGION

Optional service variables:

• POSTPLAN_PUBLIC_BASE_URL - set to a normal base URL for /d/<draft-id> URLs, or a wildcard URL such as https://*.postplan.dev for draft subdomains.
• MAX_HTML_BYTES
• UPLOAD_IP_RATE_LIMIT_WINDOW_MS
• UPLOAD_IP_RATE_LIMIT_MAX
• UPLOAD_RATE_LIMIT_WINDOW_MS
• UPLOAD_RATE_LIMIT_MAX

Uploads are public by default. Bearer API keys are still used for admin endpoints and authenticated ownership flows. The bootstrap key is inserted into Postgres on startup if present.

Railway Provisioning

After railway login succeeds, provision and deploy the first-pass stack:

chmod +x scripts/provision-railway.sh
scripts/provision-railway.sh

The script creates a Railway project, app service, Postgres service, object storage bucket, service variables, Railway domain, and first deployment. It stores the generated bootstrap API key under ~/.postplan/deployments/.

Verify the deployed service:

POSTPLAN_URL=https://your-railway-domain \
POSTPLAN_API_KEY=your-bootstrap-or-cli-key \
scripts/verify-deployment.sh

Create a named key from the bootstrap key:

curl -X POST "$POSTPLAN_URL/api/api-keys" \
  -H "Authorization: Bearer $POSTPLAN_BOOTSTRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"local-cli"}'