RailCall System Architecture & Developer Manual

A local-first Layer-2 Terminal for building, auditing, and organizing developer workflows.

RailCall Studio runs on your machine. The terminal stays the source of truth, while Studio organizes sessions, folders, workflows, integrations, artifacts, generated links, and audit receipts around it.

curl -fsSL https://railcall.ai/install.sh | bash
railcall studio

1 · What is RailCall?

RailCall is a local developer kit and Layer-2 Terminal. It is not a cloud IDE and not a fake dashboard. It gives developers a local Studio interface that organizes the real terminal, local files, workflows, API integrations, audit receipts, and generated artifacts.

2 · Quickstart

# 1 · install the CLI + Studio (offline, ~6 MB) — login · balance · audit · verify · build · studio
curl -fsSL https://railcall.ai/install.sh | bash

# 2 · authenticate + check balance
railcall login <YOUR_API_KEY>
railcall balance

# 3 · audit a file locally — zero-retention, nothing leaves your machine, signed receipt on disk
#     (make a tiny sample so the very first run can't fail)
printf 'name,email\nAda,ada@example.com\nGrace,grace@example\n' > sample.csv
railcall audit sample.csv

# 4 · verify that receipt yourself — offline, no network, no trust required
railcall verify          # re-checks what audit just minted; a tampered receipt FAILS the signature

# 5 · open RailCall Studio (the visual builder):
railcall studio          # boots Studio on 127.0.0.1:8799

Expected result: a local browser tab opens at http://127.0.0.1:<port> (default 8799).

Studio is launched from the terminal but viewed in the browser — a real interface without turning RailCall into a heavy desktop app.

3 · System Architecture

The lifecycle from signup to a running cockpit:

Webhook ingestion path

4 · Studio Interface

Launching Studio opens http://127.0.0.1:8799/v2 — three panes around a governed composer. The status bar never lies: every screen locks LOCAL · BYOK · DRY-RUN · NO SENDS until you explicitly approve a live action.

Builder — left: workspace index (workflows · integrations · monitoring · data · receipts · router) · center: governed composer + live activity ledger · right: Inspector · Proof. The engine reads RailCall · hosted — no key needed; your keys are only ever for your connectors.

Open any workflow and the Inspector proves how it will behave before it runs — dry-run by default, external writes Airlock-gated, secrets never logged:

Workflow · signup_to_sheet — a real outbound rail. Inspector proves it: dry_run YES · external touched false · writes Airlock-gated · secret_value_logged false. Nothing leaves your machine until you say so.

5 · Workflows

The build loop:

Describe → Compose → Build → Audit → Receipt → Artifact

Example Example — you say: "A lead comes in and routes to 5 employees for call/email follow-up over 2 weeks." RailCall produces a workflow spec, mapped audited pieces, needs-audit gaps, a visual artifact, a receipt, and an audit status.

Status meanings

6 · Real Multi-Connector Workflows

This is what the rail is for. A workflow is a chain of connectors — data is read out of one system, handed to the next, and dropped. Every hop crosses the Approval Airlock and appends a receipt. RailCall orchestrates across the systems you already run (and even the automation tools you already have — n8n, Make, Zapier are connectors too) without becoming the place your data lives.

To build your own, just describe it in the composer — "when a GitHub issue is labeled sev1, open a Salesforce case, run my n8n pipeline, post to Teams, and call the on-call engineer." RailCall maps each step to an audited connector, flags any gap as NEEDS AUDIT, and hands you a receipt. No step is ever silently faked.

7 · Governed Pass-Through — We Never Hold Your Data

This is the whole point. A cloud automation SaaS (Zapier, Make, n8n-cloud) sits between your systems — your customer records, payment events, and OAuth tokens land in their database. RailCall runs on your machine and is a rail, not a store: data is read from one connector, handed to the next, and dropped. The only thing that persists is the proof it happened.

Because the rail holds nothing, there is nothing on our side to breach, subpoena, or leak. Your data residency is wherever your machine and your connectors already are.

8 · Integrations / BYOK

RailCall reaches your tools through a small API / adapter stack (REST, Webhook, SQL, Email/SMTP, OAuth, plus MCP) — every integration is a config row on that stack, not bespoke code. You bring your own keys. Keys stay local — written to a 0600 vault, masked, never transmitted.

Categories: LLMs · Code & Repos · Cloud & Deploy · Databases · Payments · Comms · Docs & Workspace · Monitoring · Search & Memory · Browser Automation · Artifact Storage · CI/CD · Secrets · Analytics · Support / CRM · Automation.

Integrate — 135 reachable connections through the API stack, grouped by category, each with a risk level and a read/write scope. A slot never reads connected until a real local test passes.

Connect a tool — the flow

1. Open Integrate and search the 135 reachable connections — stripe, salesforce, twilio, n8n, github…
2. Paste your key. It's written straight to the 0600 vault, masked in the UI, and never transmitted to us.
3. RailCall runs a real local connection test against the provider. Only a passing probe flips the slot to connected — no green without evidence.
4. The connector is now available to every workflow, used in-process from your machine, under the Approval Airlock.

9 · Webhook System

The native ingestion endpoint accepts small webhook payloads, writes them to a local inbox, and appends an audit event. It does not execute untrusted code during ingestion.

For Stripe, GitHub, Shopify, Slack, etc., point the third party at your tunnel URL, not 127.0.0.1 directly:

https://your-tunnel.ngrok.app/api/webhook/stripe_payment_slot
  ↓ forwards to
http://127.0.0.1:8799/api/webhook/stripe_payment_slot

curl -X POST http://127.0.0.1:8799/api/webhook/stripe_payment_slot \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_test_123","type":"charge.succeeded","amount":5000}'

Expected response Example

{ "status": "SUCCESS", "message": "Ingested into loopback inbox" }

10 · Audit Receipts

RailCall does not call something green unless there is evidence. Every audited flow emits a receipt:

Monitor — the live receipt ledger streaming from .railcall_workspace/audit_log.jsonl, with the Airlock command states (pending · approved · executed · blocked · failed) and every governed event, newest first.

{
  "result": "PASS",
  "license_clean": true,
  "external_sockets": 0,
  "integrity_root": "sha256:39bf8abe…582a07b",
  "artifact_path": "builds/accounts_receivable_collections.html",
  "workflow_id": "accounts_receivable_collections",
  "audited_pieces": 14, "needs_audit": 0,
  "timestamp": "2026-06-21T13:31:41Z"
}

Audit a flow yourself

Every proof is on local loopback — read it with the same endpoints Studio uses:

curl http://127.0.0.1:8799/api/receipts/list   # every receipt
curl http://127.0.0.1:8799/api/audit           # latest build · external_sockets · integrity_root · human QA

• Confirm external_sockets is 0 — measured by an lsof sweep, not asserted.
• Recompute integrity_root against the spec + artifact to prove nothing drifted.
• Watch the same events stream live in the Monitor tab as the Airlock approves each step.

11 · Local Files & Directory Map

.railcall_workspace/
  workspace.json
  sessions.json
  workflows/
  folder_notes.json
  generated_links.json
  integrations.json
  commands.json
  audit_log.jsonl
  webhook_inbox/
  uploads/
  keys.local.json

Folder notes let developers remember what each folder is for without digging through code or terminal history.

12 · Total Flexibility — APIs, MCPs & Custom UIs

Because RailCall treats the terminal and local files as the source of truth, you can drive the entire system programmatically — no Studio UI required.

Calling the raw local API

Pull your active usage or workspace state into your own script, scriptable widget, or terminal toolbar. Every metric is exposed on local loopback:

curl http://127.0.0.1:8799/api/usage           # usage / balance — UNKNOWN when unverified, never faked
curl http://127.0.0.1:8799/api/data            # workflows + workspace state
curl http://127.0.0.1:8799/api/receipts/list   # every audit receipt

All read-only, all loopback-bound — the same endpoints Studio itself calls. Nothing leaves 127.0.0.1.

AI & MCP integration (Model Context Protocol)

If you use Anthropic, Claude Desktop, or a custom LLM setup, point your MCP server straight at your local .railcall_workspace/ directory.

• State context — your AI parses audit_log.jsonl or workspace.json to understand the project's real state instantly.
• Smart actions — it reads the directory map to build or modify workflows from real, audited execution states.
• Flexible execution — work straight from the terminal, call your own APIs, plug in MCP tools, or build your own aesthetic wrapper. The product molds entirely to how the dev wants to work.

13 · Your UI Is Yours — Generating the Interface

RailCall does not design UIs, and that is deliberate. We ship the programmatic source of truth — the local API, the workspace files, the audited state — and stay out of your visual layer entirely. The terminal and .railcall_workspace/ are the canonical surface; everything rendered on top of them is yours to shape.

Hand the map to a model

Want a custom dashboard, a menu-bar widget, a web panel? Point your desired model — Claude, GPT, Cursor, your own local LLM — at the map and have it generate the interface from real state, calling it with your own key (BYOK). Your model, your key, your aesthetic; RailCall just hands over the source of truth. Go back and forth with it until the layout is right.

• Feed it the map — the /api/* endpoints and .railcall_workspace/ are a complete, honest description of your system. A model has everything it needs to render it.
• Iterate — refine layout, framework, and aesthetic with the model. RailCall has no opinion on your stack.
• You own + debug it — the generated UI is your code, in your repo. Debugging the interface is a front-end task like any other: the developer's job, not ours.

Because the source of truth is programmatic and audited, any UI built on it is verifiable by construction — it can only show what the receipts already prove. We keep that core honest; you make it look like anything you want.

14 · Community — Build the Rail With Us

RailCall is built in the open with the developers who run it. Every connector on the rail started as someone's request — the roadmap is public, the audits are shared, and the fastest way to get a workflow, a connector, or a fix is to bring it to the community.

15 · Testing Manual

Step 1 — verify repo

git status
git log -1 --oneline

Step 2 — start Studio

railcall studio   # boots RailCall Studio on 127.0.0.1:8799 (port busy? STUDIO_PORT=8801 railcall studio)

Step 3 — test the local webhook endpoint

curl -X POST http://127.0.0.1:8799/api/webhook/stripe_payment_slot \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_test_123","type":"charge.succeeded","amount":5000}'

Step 4 — verify outputs

• Inbox counter increments
• Monitor feed shows the ingestion event
• Audit log receives the event
• Local inbox file contains the payload
• No execution occurs during ingestion

Step 5 — inspect the local file

ls .railcall_workspace/webhook_inbox/stripe_payment_slot/   # one .json per ingested event

16 · Troubleshooting

17 · FAQ