RailCall Docs

1 · What is RailCall?

RailCall is the intelligent execution layer beneath AI coding agents — it lets an AI understand your codebase, execute changes, optimize cost, and govern every action, all locally on your machine.

Key principles

• Local-first
• Loopback-bound
• BYOK
• No fake green
• Terminal = source of truth

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.

Layers at a glance

2 · Quickstart

From a fresh shell to a verified receipt and Studio running in five steps.

# 1 · install
curl -fsSL https://railcall.ai/install.sh | bash

# 2 · authenticate
railcall login <YOUR_API_KEY>

# 3 · audit a file
printf 'name,email\nAda,ada@example.com\n' > sample.csv
railcall audit sample.csv

# 4 · verify receipt
railcall verify

# 5 · open Studio
railcall studio

Authentication

railcall login stores a device-scoped token 0600 under ~/.railcall/. The local engine is free forever — solo use runs unlimited local work at no cost, with a signed receipt for every run. Paid plans add seats for teams ($20 / seat / month), not usage.

Updating

Studio and the CLI update in place. If Studio is running when you update the CLI, kill it first so the new binary picks up cleanly.

# Kill Studio then reinstall
railcall studio --kill
curl -fsSL https://railcall.ai/install.sh | bash

3 · System Architecture

RailCall is three lifecycles glued to one local machine: build, execute, receipt. Studio, the CLI, and the local daemon all bind to loopback.

Onboarding path

Webhook ingestion path

4 · Studio — where AI action becomes governed action

Studio is the local visual workbench that ships with the station install. It runs at http://127.0.0.1:8799/v2 — loopback-only, your data never leaves the machine unless a human clicks Approve on a specific send. The airlock is the spine. Every external effect goes through the same ceremony: preview → approve → execute → signed receipt.

The mental model

Traditional automation tools (n8n, Zapier, custom scripts) run against real providers immediately: click a button, it fires. That's a problem when AI is authoring the workflows — nobody reviewed what got composed before it hit production.

Studio inverts the flow. The LLM composes; the human approves each write; the airlock binds an approval to a specific payload hash so nothing can be tampered with between decision and execution. Every send leaves a cryptographic receipt.

The load-bearing loop

Tabs — the whole surface

The 10+ wired airlock command handlers

Ships with real handlers for the most common send targets. Each is a drop-in provider through the same ceremony — Configure in Sends, Preview, Approve, Execute, receipt.

A new provider = ~30-line handler + a VAULT_UI entry. Auth patterns proven: Bearer, Bearer+version-header, raw-key, HTTP Basic, routing-key-in-body, GraphQL, form-encoded, JSON.

What runs; what refuses

Studio deliberately catches every external side-effect at the airlock — including ones an AI proposes over MCP. The AI cannot approve; the AI cannot execute. Only a human click in Sends fires the write. Approvals are single-use: attempted once and invalidated regardless of outcome, so a captured approval cannot be replayed.

Read next

The airlock ceremony · Composing multi-step workflows · Driving workflows via MCP · Receipts + verification

5 · The airlock ceremony

Every external effect in RailCall — Discord messages, Stripe refunds, GitHub issues, Notion pages, Slack sends, PagerDuty incidents, SMS, emails, even local file writes — goes through the same three-step ceremony. It is the single load-bearing pattern in the product.

1. Preview

POST /api/commands/preview with a command id + inputs. The airlock validates the payload against the command's declared input schema, computes a payload_hash (sha256 over canonicalized inputs), records a pending approval entry, and returns an "airlock card" describing what WILL happen — including whether the send will touch an external API.

2. Approve

POST /api/commands/approve with the SAME payload. The airlock recomputes the payload_hash and binds the human approval to that exact hash. If any input changed between Preview and Approve — even a single space in a string — the hash differs, and Approve refuses.

An approval is single-use — the first Execute attempt (success OR failure) consumes it. A captured approval cannot be replayed.

3. Execute

POST /api/commands/execute. The airlock verifies: (a) approval exists for this payload_hash, (b) approval hasn't been consumed, (c) global freeze switch is off. If any check fails: blocked_by_policy, no external call, honest receipt written anyway.

On green: the approval is consumed AT THE MOMENT OF ATTEMPT (before the handler even runs — so a failed handler cannot lure the user into retrying under the same authorization). The handler makes the real external call. Whatever happens, a receipt lands.

The receipt

Verification, later

Any time, anyone, from anywhere in the world can hand a receipt to the independent auditor: railcall verify <receipt-id>. The auditor recomputes the integrity_hash from the receipt's canonical fields, re-verifies the Ed25519 signature against the install's pinned public key, checks the approval binding, and returns a fresh verdict.

Because the signature is over the integrity_hash, and the integrity_hash is over the canonical fields, a receipt cannot be forged, tampered, or replayed without invalidating the signature — even by whoever originally signed it.

Failure modes (and what happens on each)

What lives OUTSIDE the airlock

Read-only commands (list issues, read balance) don't require approval — no external state changes. They still leave a receipt so the audit trail is complete. Pure-local operations that happen INSIDE Studio (loading pages, browsing your vault, verifying a receipt) also don't need approval — the trust boundary is defined by "does this cause an external side-effect the user can't undo?"

4 · VS Code Extension

RailCall AI for VS Code is a governance HUD wired to your local Studio server over loopback: a Pending Approvals tree, a live Receipts feed, and a chat panel — all reading the same on-machine airlock as the web UI. Same BYOK vault, cost router, and PII firewall, reached directly from your editor.

The extension does not call any external service on its own. Every AI call, every Discord send, every web search routes through 127.0.0.1:8799, which enforces governance and writes a signed Ed25519 receipt (one JSON file) into your local receipts/capoffdir for every action — the feed the extension's Receipts view watches in real time.

4.1 · Prerequisites

• VS Code 1.80 or newer (also works in Cursor, VSCodium, and other MCP-era forks)
• RailCall Studio running locally — railcall studio
• At least one AI provider — a Groq key (free), Anthropic/OpenAI (paid), or Ollama (fully offline)

4.2 · Install

Option A — Direct download

Download the .vsix from railcall.ai/railcall-vscode.vsix. Then in VS Code:

1. Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
2. Type Extensions: Install from VSIX…
3. Select the downloaded file

Option B — Command line

# macOS / Linux
code --install-extension https://railcall.ai/railcall-vscode.vsix

# Windows (PowerShell)
code --install-extension https://railcall.ai/railcall-vscode.vsix

4.3 · Configure your API key

Open VS Code settings — Cmd+, (macOS) or Ctrl+, (Windows/Linux) — and search for RailCall. Paste your key into the appropriate field.

Keys are auto-synced to Studio's vault at ~/.railcall/station/.railcall_workspace/keys.local.json the moment you save the setting. To sync manually at any time, run RailCall: Sync API Keys to Studio from the command palette.

4.4 · Usage

Open the RailCall panel from the Activity Bar (left) or Secondary Side Bar (right). Keyboard shortcut: Cmd+Shift+L. The extension registers three views; the two governance surfaces come first:

• Pending Approvals — staged actions and MCP workflows awaiting a human. Click to inspect the diff or blast radius, then Approve with ✓ (a modal names you in the signed audit as approval_channel=vscode_chat) or Approve & Run with ▶, which prints the full blast radius — node count, systems touched, irreversible actions, egress domains, and spend — and distinguishes live vs mock runs and signed vs unsigned receipts.
• Receipts — a live signed-receipt feed bucketed by Today / Yesterday / Earlier. Each entry shows provider, outcome, mode, and whether it is Ed25519-signed and offline-verifiable.

The status bar shows the pending-approval count plus today's receipts, and warns on station/extension version drift. The third view is the chat panel:

Right-click any code selection for Explain, Fix, Refactor, or Generate from comment.

4.5 · How intent classification works

When you type a message, the extension uses a small AI classifier to decide whether it's a chat question, a Discord send, or a web search — instead of relying on brittle regex patterns. This means natural phrasing like "share the folder tree on discord" or "look up how React 19 handles suspense" just works.

Nothing executes without a preview and an explicit confirmation click. The classifier only routes; the action gate is always human.

4.6 · What's local vs cloud

The extension itself never phones home. Every network call is either loopback (to your own Studio) or a BYOK request you explicitly configured.

4.7 · Troubleshooting

5 · Workflows

A RailCall workflow is a linear pipeline of typed nodes. Each node receives the output of the previous one. The executor fans out automatically — if a node produces a list and the next node is a scalar processor, it runs once per item and collects results.

Workflows are local-first: the executor runs on your machine, reads your vault for credentials, and leaves a signed receipt of every run. No data leaves your machine unless a send node fires.

CSV → Discord in three commands

# 1 · save your Discord webhook (once)
railcall set discord-webhook https://discord.com/api/webhooks/{id}/{token}

# 2 · dry-run (preview — nothing is sent)
railcall workflow run contacts.csv

# 3 · go live
railcall workflow run contacts.csv --live

How it works

The template is auto-generated from your CSV column names when you omit --template. Every column becomes a {{field}} token.

CLI reference

# dry-run (no send)
railcall workflow run data.csv

# live send
railcall workflow run data.csv --live

# custom message template
railcall workflow run data.csv --template "New member: {{name}} ({{email}})" --live

# send to Slack instead
railcall workflow run data.csv --dest slack --live

# set Slack webhook
railcall set slack-webhook https://hooks.slack.com/services/…

# view current settings
railcall set

Available node types

Workflow spec (JSON)

The CLI builds the spec for you, but you can also pass one directly to the Studio API endpoint POST /api/workflow/execute for programmatic use.

{
  "name": "csv_to_discord",
  "steps": [
    { "id": "read",   "type": "csv_read",
      "config": { "path": "/data/contacts.csv" } },
    { "id": "filter", "type": "filter",
      "config": { "field": "role", "value": "founder" } },
    { "id": "format", "type": "message_template",
      "config": { "template": "{{name}} · {{email}}" } },
    { "id": "send",   "type": "discord_send", "config": {} }
  ]
}

Vault credential resolution

Any config value of the form {{vault.provider.FIELD}} is resolved from your local vault at run time. For example, setting webhook_url: {{vault.discord.DISCORD_WEBHOOK_URL}} is equivalent to leaving the field empty — the executor looks it up automatically. You can also override via environment variable: DISCORD_WEBHOOK_URL=https://… railcall workflow run data.csv --live.

Build loop status

6 · Multi-Connector Workflows

Real work spans systems. RailCall coordinates multiple BYOK connectors inside one governed flow — a single dry-run diff, a single live receipt, but writes to N systems.

7 · Governed Pass-Through

RailCall is a pass-through, not a store. Records live where they were born — Stripe rows in Stripe, Zendesk tickets in Zendesk, files in your folders. RailCall only writes signed receipts about the transitions.

This is the whole point. If RailCall ever holds your data at rest, you gain a new custodian and a new attack surface. Instead, RailCall holds the proof that a transition happened, not the record itself.

What passes through vs what persists locally

Custody & Recovery

# Rotate all local keys, keep receipt history intact
railcall keys rotate --all

# Export the last 30 days of receipts as a signed bundle
railcall receipts export --since 30d ./receipts.bundle

# Verify a bundle offline (no network)
railcall receipts verify ./receipts.bundle --offline

8 · Integrations / BYOK

Every integration is Bring-Your-Own-Key. Keys are stored locally at ~/.railcall/station/.railcall_workspace/keys.local.json with 0600 permissions — never uploaded. The provider meter (tokens, API calls) is billed direct to you; RailCall adds no markup.

Supported providers

Cost-aware routing

When multiple provider keys are present, RailCall's routing middleware classifies each request by complexity and picks the best model for the quality/cost tradeoff — automatically. You never pay for Opus on a one-line question.

The classifier is rule-based and runs in zero latency — no extra API call. It detects code signals, reasoning patterns, PII, and message length to assign a tier. Private/PII content is always routed to the local Ollama model if available.

Preferred provider & budget cap

Pin a provider or set a monthly spend cap from the CLI or Studio:

# always use Anthropic regardless of task type
railcall set preferred-provider anthropic

# let the router decide (default)
railcall set preferred-provider auto

# cap monthly spend at $5 — router demotes tier at 90%
railcall set budget 5

Multi-provider fallback chain

If the preferred or cost-optimal provider fails (rate limit, bad key, quota exceeded), the router tries the next provider in the chain automatically: groq → anthropic → openai → xai → ollama. Every fallback is logged with a reason so the routing is fully auditable.

Connect flow

1. Run railcall set <provider>-key <key> — written to vault at 0600.
2. Open Studio → the routing badge in the model picker shows the active provider, estimated cost per message, and budget remaining.
3. Click the badge to open the Router Config panel: change preferred provider or budget without touching the CLI.
4. Run railcall cost anytime to audit spend by provider and model.

9 · Webhook System

Inbound webhooks are first-class. Each one is a signed, scoped endpoint bound to loopback and reachable through your own tunnel.

Properties

Tunnel path

Test command

# Fire a signed test event against a local webhook
railcall webhook test stripe.payment_intent.succeeded \
  --endpoint http://127.0.0.1:8787/hooks/stripe \
  --payload ./fixtures/pi_succeeded.json

Expected response

{
  "accepted": true,
  "event_id": "evt_1PXY…",
  "receipt": "rcpt_ingest_01H…",
  "queue_position": 1,
  "next": "airlock_decide"
}

10 · Approval Policy

Every write crosses a governance floor. The floors are fixed; only scoped, signed policies can move the line — and policy changes are themselves governed writes.

Four hard floors

Policy change flow

A policy change is itself a governed write. Propose in Studio or CLI, compute the delta against the active policy, sign an Ed25519 approval receipt, then land the new policy — the old one is archived, never deleted.

11 · Audit Receipts & Evidence Ledger

Every governed write mints a receipt. Receipts are JSON, Ed25519 signed, and offline-verifiable. Together they form the Evidence Ledger.

Receipt example

{
  "receipt_id": "rcpt_01H8Z…",
  "kind": "flow.live",
  "flow_id": "flw_stripe_recon_v3",
  "policy_id": "pol_widen_01",
  "integrity_root": "sha256:9a4c…f0",
  "connector_writes": [
    { "connector": "sheets", "range": "Payouts!A87:F87", "hash": "sha256:2b…" },
    { "connector": "email",  "message_id": "<a1@srv>",   "hash": "sha256:7e…" }
  ],
  "sockets_observed": 0,
  "approver": "sami@localhost",
  "signature": "ed25519:MEUCIQD…",
  "at": "2026-07-10T12:04:11Z"
}

Field reference

Audit commands

# List recent receipts
curl -s http://127.0.0.1:8787/v0/receipts?since=24h

# Verify one receipt end-to-end (offline)
railcall audit rcpt_01H8Z… --verify --offline

# Diff two receipts on a run
curl -s http://127.0.0.1:8787/v0/receipts/diff?a=rcpt_a&b=rcpt_b

# Export a bundle for compliance review
railcall receipts export --flow flw_stripe_recon_v3 ./out.bundle

12 · Payment Rails

RailCall governs money movement like any other irreversible action — draft, dry-run, approve, settle, receipt. Its own pricing is per seat, not per payment.

Plans & pricing

Local runs stay free and unmetered even on paid — you pay for seats (people), not usage. Free for one, $20 / seat for your team.

# See your plan and seats
railcall plan
# Local runs are free and unmetered — there is no balance to check.

Governed payment flow

x402 Agent Economy

13 · Local Files & Directory Map

RailCall keeps everything under ~/.railcall/. The tree is human-readable — nothing about your setup is opaque.

~/.railcall/
├── keys/            # BYOK provider keys · 0600 · never leaves loopback
├── flows/           # Workflow definitions
├── receipts/        # Append-only Ed25519 signed evidence ledger
├── artifacts/       # Files produced by flows (reports, exports)
├── policies/        # Signed policy documents
├── connectors/      # Per-connector config and scope receipts
└── logs/            # Local diagnostic logs (rotated, no secrets)

Folder reference

14 · Total Flexibility

Studio is one client. The daemon exposes a local HTTP API — any tool that speaks HTTP can drive RailCall. All endpoints are loopback-bound.

# List active flows
curl -s http://127.0.0.1:8787/v0/flows

# Trigger a dry-run of a specific flow
curl -s -X POST http://127.0.0.1:8787/v0/flows/flw_stripe_recon_v3/run \
     -H "content-type: application/json" \
     -d '{"mode":"dry-run"}'

# Fetch a receipt by ID
curl -s http://127.0.0.1:8787/v0/receipts/rcpt_01H8Z…

15 · MCP Integration

RailCall ships an airlock MCP server that any MCP client — Claude Code, Claude Desktop, Cursor, or your own agent — can drive over stdio JSON-RPC. It exposes 69 tools: a matched _plan / _apply pair for each of the 24 governed integrations, plus a read-only toolbelt that lets an agent understand a codebase, reason locally, compose governed workflows, and attest its own actions. Every write is dry-run by default; live execution requires an explicit consent token.

Server identity

Governed integrations (plan + apply)

Each integration exposes two tools: <provider>_<verb>_plan (dry-run, returns a diff and a consent_token) and <provider>_<verb>_apply (executes the plan under the returned token, emits a signed receipt).

The last two are the bridge to governed engineering: an AI-proposed code patch stages a diff you approve in the editor, then writes it root-jailed and reversibly with a signed receipt; test runs execute only human-configured command aliases — the model can never smuggle a raw shell command through.

The read-only toolbelt

Beyond sends, the agent gets a deterministic, root-jailed toolbelt so it can prepare a change without spending frontier tokens on a repo dump — and attest what it did. All local, all offline.

Read-only inspection

Safe to call at any time. No workspace mutation, no external network writes.

Airlock guarantees

Claude Code

One command, user scope so the server is available in every project:

claude mcp add \
  --scope user \
  --transport stdio \
  --env RAILCALL_WS="$HOME/.railcall/workspace" \
  railcall -- python3 "$HOME/.railcall/station/workbench/mcp_server.py"

Verify with claude mcp list — you should see railcall: ... ✓ Connected. Restart Claude Code once so the tool schemas inject into the session.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "railcall": {
      "command": "python3",
      "args": ["/Users/you/.railcall/station/workbench/mcp_server.py"],
      "env": {
        "RAILCALL_WS": "/Users/you/.railcall/workspace"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (or the workspace-scoped .cursor/mcp.json):

{
  "mcpServers": {
    "railcall": {
      "command": "python3",
      "args": ["/Users/you/.railcall/station/workbench/mcp_server.py"],
      "env": {
        "RAILCALL_WS": "/Users/you/.railcall/workspace"
      }
    }
  }
}

Enabling live apply

By default, _apply tools return a preview even with a valid consent token — the airlock stays sealed. To let apply calls execute against real providers, set:

export RAILCALL_MCP_ALLOW_LIVE=1

in the MCP server's env block. The hard floor still holds: irreversible spend actions require an out-of-band human confirmation regardless of this flag.

16 · Your UI Is Yours

Studio is the reference interface. It isn't the only one you can use.

Hand the map to a model

• Expose state. Point Claude (or any MCP-aware model) at railcall_integrations_list and railcall_receipts_list. Read-only, zero widening risk.
• Ask for a proposal. The model calls <provider>_<verb>_plan — stages a dry-run and gets a diff plus a consent_token. Nothing external happens.
• You approve. Approve in Studio, CLI, or your own UI. The receipt lands regardless of where you clicked — governance is client-independent.

17 · Community

RailCall is built in the open with a small, active community of local-first engineers. If you use it, we'd rather hear the honest edge cases than the polished demos.

Request a Connector

Open a thread with the provider name, the smallest useful surface (one endpoint is fine), and a link to their API docs. We prioritize connectors that unlock a full workflow, not just a call.

Ship a Workflow

Contribute governed workflows as PRs to railcall-core. Every accepted workflow ships with its build receipt and a reproducible test.

Product Improvements

File issues with a reproduction, the receipt IDs involved, and what state was UNKNOWN. Verified reports get priority.

Audited Not Anecdotal

The community norm: back claims with receipts. "It works" isn't enough — rcpt_… is.

18 · Testing Manual

Five steps to smoke-test a fresh install. If any step returns UNKNOWN or fails, stop — that's the bug.

curl -fsSL https://railcall.ai/install.sh | bash
railcall --version   # must print a semver

railcall login   # stores device token 0600
railcall plan    # shows Free (solo) — unlimited local runs

railcall demo run --dry-run
# Expected: single signed dry-run receipt, sockets_observed = 0

railcall audit demo --verify --offline
# Expected: OK · signature valid · integrity_root matches

railcall studio
# Open http://127.0.0.1:8787 in your browser

19 · Troubleshooting & FAQ

Common issues

Quick reference