Native setup (macOS + launchd)¶
Everything runs as normal processes on your Mac, started by launchd.
Prerequisites¶
- macOS with Python 3.11+
- An IBKR account with a paper (or free-trial) login
- IB Gateway (stable channel)
- An Anthropic API key, or an OpenRouter key (see How to use → LLM provider)
1. Install¶
git clone https://github.com/saifulislamamiyo/guardrail-trader.git
cd guardrail-trader
python3 -m venv .venv
.venv/bin/pip install -e ".[dev,tools]"
cp .env.example .env # add your API key; keep TRADING_MODE=paper, IBKR_PORT=4002
Never commit .env
It holds your API key. It is already in .gitignore.
2. Configure IB Gateway¶
- Log in to IB Gateway with Paper Trading selected.
- Configure → Settings → API → Settings:
- Enable ActiveX and Socket Clients: on
- Read-Only API: off (the bot has its own read-only mode)
- Socket port:
4002 - Allow connections from localhost only: on
- Leave it running and logged in.
3. Verify, then dry-run¶
.venv/bin/python scripts/check_connection.py # read-only: account, positions, a quote
.venv/bin/python scripts/journal_cli.py init # deposit the virtual budget (once)
.venv/bin/python scripts/run_bot.py --dry-run --fake-claude # whole harness, no API cost, no orders
.venv/bin/python scripts/run_bot.py --dry-run # real Claude, nothing sent to IBKR
.venv/bin/python -m pytest -q # tests need no broker or key
check_connection.py refuses to continue if the port is a live port or the account ID is not a
paper account (paper IDs start with DU).
4. Run unattended¶
scripts/launchd.sh render # print the three plists first (installs nothing)
scripts/launchd.sh install # scheduler, keep-awake, dashboard
scripts/launchd.sh status
That's it: from now on, two runs happen per US trading day, and the dashboard is at http://127.0.0.1:8765. See Operations for what the LaunchAgents contain and how to remove them.
Keep the lid open
caffeinate -i -s prevents idle sleep only. Closing the lid still sleeps a MacBook (unless
it's on power with an external display), and a sleeping Mac misses its runs.