Reference
Installation and configuration.
Find installation requirements, configuration files and connection settings. The beginner broker guides cover the initial read-only connection and account check. For a first visit, follow the beginner setup lesson first.
Supported computers
The packaged app supports a Mac with Apple Silicon and a Windows PC running 64-bit Windows 10 or 11. Intel Macs are not supported. Windows is supported. Check the download page for the current installer; if availability cannot be confirmed, contact support. NinjaTrader 8 runs on the same Windows PC as BrokerBridge.
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 the Local simulated account. It cannot run NinjaTrader 8.
- Broker. Optional. The Local simulated account needs no broker. 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
- Credits. Free to start on the Local account. Live trading and paid AI models need Personal Credits, from $10
- No Python install for the packaged app.
The full list lives on system requirements.
Local and activation
- 1. Install the package from the download page.
- 2. Start on the free Local account with simulated money. Read the fictional practice plan first; connect an AI model when you want to save a draft for review.
- 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.10 | Default maximum single-position allocation: 10% of account value. This is not the planned loss at the stop. |
| 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. |
Saved settings take precedence over defaults. Read the values in your own Settings before relying on an example. The risk and sizing lesson explains allocation, planned loss, and total exposure with numbers.
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.
- No Windows download, or the NT8 walkthrough is not published
- Check the download page for current installer availability. A setup walkthrough may remain unpublished while its native steps and privacy review are verified; that does not change the supported platform list. Use the published setup path or contact support for the unavailable step.