paperclip-platform-railway.plan

Paperclip for platform team (in-repo, Railway)

Scope

• Audience: Platform team first. Paperclip company/goals/projects represent platform work (e.g. Forge features, infra, agent orchestration), not the full Brainforge portfolio.
• Location: Paperclip lives under the monorepo at apps/paperclip (no separate repo).
• Deploy: One Railway service for Paperclip, built and run from apps/paperclip. It can live in the same Railway project as other Brainforge services, but it should be treated as a separate service with its own env and database.

Do we need to create it outside the monorepo?

No. For the platform team pilot, Paperclip should live in-repo and deploy to Railway like any other app.

• In-repo: Add apps/paperclip by bringing in the paperclipai/paperclip code (see “Adding Paperclip under apps” below).
• Railway: Create a new service with apps/paperclip as the service root. Railway should build and start Paperclip from there, with its own domain and env vars. No separate repo needed.

Adding Paperclip under apps

Single source strategy: Git subtree

• Add Paperclip as a subtree from paperclipai/paperclip (master) into apps/paperclip, same pattern as OpenWork (apps/openwork) and Dagster (apps/dagster-pipelines).
• Keep the subtree intact so upstream syncs stay simple. Document the import/update command in playbook the same way OpenWork does.
• If the subtree proves too heavy later, that becomes a follow-up optimization, not the starting point.

Monorepo details

• Paperclip uses pnpm and a pnpm workspace. The repo root uses npm for platform. So:
  • Local dev runs from apps/paperclip (pnpm install, then pnpm dev).
  • Add a root convenience script only if useful, but do not make the root package manager responsible for Paperclip.
  • Railway build and start should happen from apps/paperclip and should use Paperclip’s own pnpm scripts.

Railway deploy

• New service: In your Railway project, add a service that:
  • Root: apps/paperclip
  • Build: pnpm install && pnpm build from apps/paperclip
  • Start: Use Paperclip’s actual start script from its package.json or Dockerfile
  • Env: Wire Paperclip’s exact required env vars from upstream, backed by Railway Postgres plus 1Password-managed secrets
• Port: Paperclip listens on one port (e.g. 3100); Railway assigns a public port/URL. No conflict with Platform (3000) or Dagster (3001).
• Docs: Add a short section in standards/03-knowledge/engineering/setup/paperclip-setup.md: in-repo path, how to run locally, Railway service name/URL, env vars (with 1Password references).

Platform-team-specific setup inside Paperclip

Once Paperclip is running (locally or on Railway):

• Company: One company, e.g. “Brainforge” or “Brainforge Platform.”
• Goals: Platform-team goals (e.g. “Ship Forge features,” “Maintain platform reliability,” “Run agent workflows”).
• Projects: Create projects under those goals (e.g. “Forge roadmap,” “Paperclip integration,” “Linear ↔ Platform sync”).
• Agents: Start with one deterministic worker path: a Bash/HTTP worker that can receive a task, run the mapped platform action, and report completion. Cursor adapter support can be added later, but it should not block the first rollout.
• Heartbeats / budgets: Configure heartbeat schedule and per-agent budgets so platform-team agents run and don’t overrun cost.

Summary

Question	Answer
Create Paperclip outside the monorepo?	No. Add it under apps/paperclip and deploy that app to Railway.
Where does it live?	apps/paperclip as a git subtree from paperclipai/paperclip.
How do we run it?	Locally: cd apps/paperclip && pnpm install && pnpm dev. In production: Railway service building and running the Paperclip app from apps/paperclip.
Who is it for first?	Platform team (company/goals/projects scoped to platform work).

Learnings (deployment retrospective)

Deployment and configuration learnings (monorepo deploy, Railway constraints, Better Auth, adapter env, domain strategy) are in knowledge/engineering/paperclip-railway-deployment-learnings-2026-03.md. Use them to update playbook, skills, and future “deploy new service” flows.

Next steps (implementation)

1. Add apps/paperclip as a git subtree and document the import/update flow in playbook.
2. Add a short paperclip-setup.md doc with local commands, Railway service root, and the exact upstream env contract.
3. Create the Railway service for apps/paperclip, connect Postgres, and deploy the first version.
4. Create the Paperclip company, platform-team goals, and one pilot project.
5. Implement one Bash/HTTP worker path for the first task type and wire heartbeats to it.
6. Only after the pilot works, consider Cursor adapter support or Linear sync on completion.