Railflow local runner

Run Railflow jobs on your own device — for free — using the AI coding tools you already pay for: your Claude Code (Claude Pro/Max) or Codex (ChatGPT) subscription, or your own Anthropic/OpenAI API keys.

How it works

• The runner is a small CLI that pairs with your Railflow workspace and polls for jobs you start with Run on: My device in the app.
• It executes each job by driving the official claude or codex CLI, installed and signed in by you, on your machine.
• Your Claude/Codex login and provider API keys never leave this device. Railflow carries job text, status updates, QA evidence, and (for QA jobs only) the workspace test configuration you explicitly saved in Railflow. That temporary QA env is restored or removed when the run ends. Inference is billed by Anthropic/OpenAI directly to your account.
• Results land in the same place as cloud jobs: the job chat, the task board, testing criteria, branch links — identical experience, zero Railflow credits.

Setup

1. Install and sign in to at least one engine on this machine:
   • Claude Code — https://claude.com/claude-code — run claude once and sign in with your Claude account (or set ANTHROPIC_API_KEY).
   • Codex — https://developers.openai.com/codex — run codex once and sign in with ChatGPT (or set OPENAI_API_KEY).
2. In the Railflow app: Settings → Connections → Local runner → Connect this computer to get a pairing code.
3. Pair and install:

npm install -g railflow-local
railflow-local connect pair-XXXX-XXXX
railflow-local install

Install globally rather than via npx: the background service needs a stable path on disk, and npx runs from a cache npm prunes on its own schedule. (install will refuse to register a service from an npx cache for this reason.)

install registers a background service (launchd on macOS, systemd on Linux) that starts at login, restarts if it crashes, and survives reboots — there is no terminal window to keep open. Jobs you send to "My device" are picked up within a few seconds.

Run railflow-local status to check on it, railflow-local uninstall to stop it, or railflow-local start to run it in the foreground instead.

Git access

Repos are cloned with your own git credentials (gh auth login, SSH key, or credential helper). Railflow never supplies or receives a git credential on the local path.

Permissions

By default the agent runs with --permission-mode acceptEdits (Claude Code) and --full-auto (Codex): it can edit files and run commands inside the cloned working copy under each CLI's own sandboxing rules. Set RAILFLOW_SKIP_PERMISSIONS=1 to run Claude Code with --dangerously-skip-permissions — only do this on a machine you'd trust an autonomous agent on.

Terms of service

This runner exists to keep you compliant: it never extracts, stores, or proxies subscription OAuth tokens, never spoofs another tool's identity, and calls no unofficial endpoints. Everything runs through the official CLIs, under your own account, on your own hardware, at individual scale. Your use of Claude Code and Codex remains governed by Anthropic's and OpenAI's own terms, and subscription-mode availability is subject to their policies.