Deploy and Host NakatomiCRM on Railway

Nakatomi is a headless, agent-native CRM. No human UI to click through — every primitive (contacts, companies, deals, pipelines, activities, notes, tasks, files, relationships, timeline, webhooks) is a REST endpoint and also an MCP tool. Built for Claude, ChatGPT, Cursor, and Perplexity.

About Hosting NakatomiCRM

Hosting Nakatomi means running a single FastAPI + Postgres service behind Railway's TLS edge. The Dockerfile runs Alembic migrations, boots uvicorn with proxy-header awareness, starts a durable webhook worker, and mounts an MCP server at /mcp. OAuth 2.1 + dynamic client registration is baked in so Claude Desktop's GUI connector works out of the box; bearer API keys handle Claude Code, Cursor, and raw HTTP clients. A single 512 MB instance paired with Postgres handles thousands of contacts easily. Files go to a mounted volume by default, or plug in S3/R2 via env vars.

Common Use Cases

• Give Claude Desktop, Cursor, or Perplexity a persistent, structured CRM they can create/search/mutate via native MCP tools.
• Back a custom sales frontend (or a headless LLM workflow) with a typed REST API that speaks bulk upsert, cursor pagination, and idempotency keys.
• Ingest CSV, vCard, JSON, or free-text contact lists through /ingest, then enrich and deduplicate via fuzzy /duplicates + /merge.

Dependencies for NakatomiCRM Hosting

• Postgres 16 with pg_trgm (provisioned automatically by this template).
• A mounted volume (/app/data) for local file storage — or S3-compatible credentials if you prefer object storage.

Deployment Dependencies

• Nakatomi repo
• Deployment playbook — 13 gotchas we hit on the first Railway deploy, fully documented
• MCP tool manifest
• Agent capability card (A2A) and /llms.txt for LLM discovery

Implementation Details

Nakatomi is built to be configured by an agent. Grab your service URL from Settings → Domains in the Railway dashboard, then hand this prompt to Claude Code, Cursor, or any tool-using LLM:

Paste into your agent:

> I just deployed Nakatomi CRM at https://.up.railway.app. Set it up for me: > > 1. Call POST /auth/signup with my email, a password I'll give you, and workspace_slug: "mine". Save the returned access_token. > 2. With that JWT, call POST /workspaces/api-keys with {"name":"primary","role":"admin"}. Return the key value exactly once so I can copy it. > 3. Confirm the install by fetching /schema and tell me how many entities and event types it exposes. > 4. Store my base URL + API key in your connection for future use. > > My email is [email protected]. I'll send the password in my next message.

That prompt produces a working workspace, an API key, and a connection the agent can reuse on every subsequent request — no curl, no jq, no manual copy-paste.

For Claude Desktop (GUI, no terminal): Settings → Connectors → Add Custom Connector → paste your Railway URL. OAuth 2.1 discovery handles the rest — sign in with the email/password you used in step 1.

Manual path (if you insist):

BASE=https://.up.railway.app

# 1. signup → JWT
curl -sS -X POST $BASE/auth/signup -H 'Content-Type: application/json' -d '{
  "email":"[email protected]","password":"hunter2hunter2",
  "display_name":"You","workspace_name":"My Workspace","workspace_slug":"mine"
}'

# 2. JWT → API key
curl -sS -X POST $BASE/workspaces/api-keys -H "Authorization: Bearer $JWT" \
  -H 'Content-Type: application/json' -d '{"name":"primary","role":"admin"}'

# 3. sanity check
curl -sS $BASE/health && curl -sS $BASE/schema | jq '.entities | length'

Bearer clients (Claude Code, Cursor, SDKs): send Authorization: Bearer nk_live_… + X-Workspace: mine on every request.

Why Deploy NakatomiCRM on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying NakatomiCRM on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.