# PitBridge quickstart One install, then four small steps. Want to look before you leap? A safe paper demo boots with no config at all. Every path below stays in paper mode with all 12 guardrails on and live execution locked. Pick the runtime you already use. Canonical page: https://pitbridge.com/docs/quickstart/ ## Try the demo first The fastest way to see PitBridge is to run the MCP server with no config at all. With nothing in `~/.pitbridge/`, `pitbridge mcp` boots a safe paper DEMO sandbox: a fake account, all 12 guardrails on, and live execution locked. It has no broker link and cannot place a real order, so it never crashes for want of setup. ```sh uvx pitbridge mcp # no config found: booting a safe paper DEMO sandbox. # fake account, all 12 guardrails on, live locked. # your agent can now call get_accounts and get_guardrail_status. ``` Point any MCP client at it and your agent can immediately call `get_accounts` and `get_guardrail_status` to see the tools and the guardrail engine before you configure a single thing. When you are ready to point it at your own NinjaTrader account, do the four-step setup below. ## Install, safe by default PitBridge is a Python package (requires uv, https://docs.astral.sh/uv/): ```sh uv tool install pitbridge # or skip the install and run any command with uvx: uvx pitbridge doctor ``` A fresh install cannot place a live order. The default mode is paper, every guardrail is on, and `pitbridge arm-live` refuses because the open core ships no live execution provider. There is no agent tool to change any of that. See the security model: https://pitbridge.com/docs/security-model/ Availability note: PitBridge is published on PyPI; `uvx pitbridge` resolves and runs. It is early, pre-1.0 software under active development, so stay in paper mode and read the security model (https://pitbridge.com/docs/security-model/) before pointing anything at a funded account. ## Set up in four steps Point PitBridge at your own account with four commands. Everything stays in paper mode until you deliberately unlock live. ### 1. Scaffold the config `pitbridge init` writes a starter `~/.pitbridge/config.toml` you can edit. It never overwrites an existing file unless you pass `--force`. ```sh uvx pitbridge init # wrote ~/.pitbridge/config.toml # already there? overwrite with: uvx pitbridge init --force ``` ### 2. Edit your config Open `~/.pitbridge/config.toml` and set your NinjaTrader account name and the guardrail values you intend to trade under. This example defines one paper account against NinjaTrader's built-in Sim101 (example values, yours to choose): ```toml [daemon] bind = "127.0.0.1" port = 8873 paired_mode = false pairing_token = "pb_pair_demo" # generate your own: pitbridge pair new [accounts.sim] nt_account = "Sim101" mode = "paper" # read_only | paper | live (live needs the Pro plugin + arm-live) profile = "eval" [accounts.sim.guardrails] instruments = ["MES 09-26"] max_contracts_per_order = 2 daily_loss_halt = 500 trading_window = { tz = "America/New_York", open = "09:30", close = "16:00" } ``` Orders need somewhere to go: the PitBridge add-on inside NinjaTrader 8 connects out to the daemon on port 8873. Until that link is up and reconciled, every order is refused with `LINK_DOWN`. Fail closed: no link, no orders. ### 3. Run the MCP server, or wire it into your agent `pitbridge mcp` is the stdio MCP server your agent attaches to. Run it directly to check it starts, or register it inside the runtime you already use (Claude Code, Claude Desktop, and OpenClaw are below). ```sh uvx pitbridge mcp # stdio MCP server, reads ~/.pitbridge/config.toml # custom path? append: --config /path/to/config.toml ``` ### 4. Verify with doctor `pitbridge doctor` runs a read-only self-check and prints a PASS, WARN, or FAIL line per section: config, accounts, guardrails, deny-list, kill switch, live gate, and version. Run it whenever something looks off. ```sh uvx pitbridge doctor # read-only self-check, one line per section: # config PASS ~/.pitbridge/config.toml # accounts PASS 1 paper account (sim -> Sim101) # guardrails PASS 12 on # deny-list PASS 0 instruments blocked # kill switch PASS not engaged # live gate PASS locked (no pro plugin) # version PASS pitbridge 0.1.1 ``` ## Claude Code 1. Register the MCP server (stdio) with one command: ```sh claude mcp add pitbridge -- uvx pitbridge mcp # custom config path? append: --config /path/to/config.toml ``` 2. Check it is connected: `claude mcp list`. 3. Ask Claude for your guardrail status. It calls `get_guardrail_status` and reads the limits back. 4. Ask it to buy 1 MES on the sim account, then ask it to buy 10. The first fills in paper; the second is blocked with `MAX_CONTRACTS_PER_ORDER`. Claude sees nine tools: five reads (get_accounts, get_positions, get_orders, get_account_state, get_guardrail_status) and four order actions (place_order, cancel_order, close_position, flatten_account). There is deliberately no tool to release the kill switch, arm live, or edit a limit. ## Claude Desktop 1. Open `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`). 2. Add the server block: ```json { "mcpServers": { "pitbridge": { "command": "uvx", "args": ["pitbridge", "mcp"] } } } ``` 3. Restart Claude Desktop. The pitbridge tools appear in the tools menu. 4. Same test as above: a small order fills in paper, an oversized one is blocked with a reason. A one-click `.mcpb` bundle for Claude Desktop, with guardrail settings in the native settings UI, is in progress. ## OpenClaw 1. OpenClaw attaches MCP servers over stdio. Register `uvx pitbridge mcp` as a server command in your OpenClaw MCP configuration, the same shape as any other stdio server. 2. Restart the agent and list tools. You should see the nine pitbridge tools. 3. Tell your agent the account is paper and let it read `get_account_state` before anything else. A packaged `pitbridge-trading` skill (a thin wrapper over these MCP tools with the security story up front) is in progress. After ClawHavoc, read the source of any trading skill before you run it, this one included. The source repository (https://github.com/ToolstackVault/pitbridge) is being opened up alongside launch. ## MCP over HTTP: on the roadmap Honest status: today PitBridge serves MCP over stdio only. A local streamable HTTP endpoint for MCP-over-HTTP clients such as Hermes is on the roadmap (https://pitbridge.com/roadmap/) and is not in the current build. Until it ships, two routes work now: 1. Any client that can launch a stdio MCP server: register `uvx pitbridge mcp` as the server command, the same shape as the Claude Code section above. 2. Custom agents and scripts: use the localhost REST API below. Same guardrail verdicts, same audit log, no MCP client required. Whatever the transport, the daemon binds to localhost. A non-localhost bind requires paired mode plus a pairing token before the daemon will start. ## Plain REST and curl 1. Start the daemon: `uvx pitbridge run` 2. Read account state: `curl -s http://127.0.0.1:8873/v1/account_state` 3. Place a paper order that passes: ```sh curl -s -X POST http://127.0.0.1:8873/v1/place_order \ -H 'content-type: application/json' \ -d '{"account":"sim","instrument":"MES 09-26","side":"BUY","qty":2}' # expect "outcome":"SUBMITTED" ``` 4. Break a rule on purpose: ```sh curl -s -X POST http://127.0.0.1:8873/v1/place_order \ -H 'content-type: application/json' \ -d '{"account":"sim","instrument":"MES 09-26","side":"BUY","qty":20}' # expect "outcome":"BLOCKED", "reason_code":"MAX_CONTRACTS_PER_ORDER" ``` 5. Ask why, and prove the log is intact: `pitbridge audit why `, then `pitbridge audit verify`. There is also a WebSocket event feed at `ws://127.0.0.1:8873/v1/ws` for order, fill, and guardrail events. Example values above are example config, not recommendations. ## Troubleshooting with doctor When an order is refused, a client will not connect, or you just want to confirm the state, `pitbridge doctor` is the one command to reach for. It is read-only and changes nothing. It reports config, accounts, guardrails, the deny-list, the kill switch, the live gate, and the version, each as PASS, WARN, or FAIL. A FAIL points you straight at the part of the setup to fix; for a single order decision, `pitbridge audit why ` explains that specific block. ## What to read next - Security model: https://pitbridge.com/docs/security-model/ - The twelve guardrails: https://pitbridge.com/product/guardrails/ - Pricing (free paper, Pro unlocks live): https://pitbridge.com/pricing/ ## Legal PitBridge is trading infrastructure, not financial advice. Futures trading involves substantial risk of loss and is not suitable for every investor. NinjaTrader is a registered trademark of NinjaTrader, LLC; PitBridge is an independent project and is not affiliated with, endorsed by, or sponsored by NinjaTrader, LLC.