Browse documentation
Reference
Installation and configuration.
Use this reference for the durable setup facts that sit beside the beginner broker chooser. Start with Practice, keep the first broker connection read-only, and verify paper or SIM identity before any optional order chapter.
Current support boundary
The packaged app runs on a Mac with Apple Silicon today; a Windows PC (64-bit Windows 10 or 11) is on the waitlist and will need the same once it ships. Intel Macs are not supported. NinjaTrader 8 is Windows-only. Do not treat a source checkout as a customer install.
System requirements
- Computer. A Mac with Apple Silicon (M1 or later) on macOS 12 Monterey or later, or a Windows PC running 64-bit Windows 10 or 11. Intel Macs are not supported. There is no phone or tablet app.
- NinjaTrader 8. Windows only. BrokerBridge and NinjaTrader 8 must run on the same Windows PC. A Mac can run BrokerBridge with Interactive Brokers or Practice. It cannot run NinjaTrader 8.
- Broker. Optional. Practice needs none. Connect Interactive Brokers when you want paper or live routing. TWS or IB Gateway runs on the same computer, Mac or Windows.
- Network. Needed to download the app and use managed AI or market data
- AI credits. Optional later. Free to start; pay only for AI credits when you need more compute
- No Python install for the packaged app.
The full list lives on system requirements.
Practice and activation
- 1. Install the package from the download page.
- 2. Choose Practice and build one complete plan without a broker.
- 3. Create an account and managed AI credits only when needed.
- 4. Connect an IBKR paper or NT8 Sim path only after its identity and mode are clear.
Installation
Use the current packaged installer. The private retail repository and editable source environment are contributor paths, not customer installation instructions. If the download or launch surface is unavailable, stop and use Troubleshooting.
IB Gateway and TWS paper setup
Use the official Interactive Brokers paper login, then configure the broker application before opening BrokerBridge. Gateway uses paper port 4002; TWS uses paper port 7497. Keep Read-Only API enabled for the first connection.
- Open the broker application's API settings and confirm socket clients are enabled.
- Confirm the paper port and keep the paper login visible.
- In BrokerBridge Setup Wizard, choose the matching paper preset. The server assigns a free local Client ID during the test; it is not an account number.
- If more than one account is returned, select the masked paper account and test again. Finish only after authenticated identity and paper mode are shown.
- Run IBKR Diagnostics after setup and repeat the identity check after a restart.
Live ports 4001 and 7496, funded accounts, and live order instructions are outside this beginner reference. Stop if the broker screen is not clearly paper.
Configuration schema and defaults
The packaged app keeps its managed configuration at $BROKERBRIDGE_HOME/config.yaml, defaulting to ~/.brokerbridge/config.yaml. Prefer Settings and the packaged app controls over hand-editing.
| Key | Default or safe first value | Meaning |
|---|---|---|
| broker.host | 127.0.0.1 | Local broker application endpoint. |
| broker.port | 4002 / 7497 | Paper Gateway / paper TWS socket. |
| broker.client_id | server-assigned for guided paper setup | Identifies the local API connection; never use it as an account number. |
| risk.max_position_pct | 0.05 | Maximum single-position fraction. |
| risk.max_open_trades | 1 | Account-wide open-lot ceiling. |
| risk.daily_pnl_cap_pct | 0.03 | Daily loss cap as a fraction. |
| risk.require_stop_loss | true | Refuses plans without a defined stop. |
Never paste a config file, token, password, account number, or install grant into a ticket, chat, screenshot, transcript, or public document.
Credentials
BrokerBridge-managed AI credits do not require customers to create or supply provider API keys. Broker credentials stay in the local broker application. The beginner guides only use paper or SIM accounts and never ask for credentials in documentation captures.
Risk settings and semantics
- Set loss, size, and trade-count limits before connecting a broker.
- Values ending in
_pctare fractions in config:0.05means 5%. - An empty
disabled_gateslist keeps the named gates active. Removing a floor requires an explicit in-app confirmation. - Keep the first IBKR API connection read-only and confirm the masked account plus paper mode.
- Only the separately gated paper/SIM LIMIT chapter may change order permission.
- Live, funded, unknown-account, and
nt8_livepaths are outside this reference and must remain refused.
Common setup issues
- Port reachable, session not verified
- Keep the broker app in paper mode, confirm the selected port, and retry. A listening socket is not proof of account identity.
- Account selector appears
- Select the masked paper account, test again, and stop if the mode or account is unknown.
- Client ID allocation reports a collision
- Stop another local BrokerBridge session and retry. Do not replace the assigned ID with a copied value from a screenshot.
- Windows or NT8 path unavailable
- That path is not a supported customer release until native package, topology, and privacy capture gates pass. Use Practice on the supported package.