Install the Runner
The Runner is a small program that trades a playbook on your own computer, through your own broker account. We never see your keys or your money. This page is everything you need — nothing else.
Trying it free (from an email link): 1) unzip the Runner anywhere; 2) run start.cmd doctor (Mac/Linux ./start.sh doctor) to check your setup; 3) start.cmd run trades the bundled starter — dry-run by default, no accounts, no risk; 4) start.cmd verify reads the rulebook out loud, rule by rule, before you run anything for real. The bundled starter is a frozen demo — it never updates — but reading it, back-testing it, and even trading it in dry-run, paper, or live all work with no license key at all; only a purchased rulebook ever asks for one.
Watch the step-by-step Windows guide
New to this? This one video walks you through installing the Runner and connecting an Alpaca paper-trading account, using pretend money. Follow the slower narration, on-screen captions, and pauses at your own pace.
What you need
- A Windows, Mac, or Linux computer
- Node.js, version 20 or newer — free, from nodejs.org
- A free Alpaca account, with paper keys — only if you want to connect a paper account (Path B below); dry-run needs neither. The same keys also let the Runner scan the whole market on your machine (see "What's in a purchased file")
- Your license key — only if you bought a playbook and want to trade it; the bundled starter runs without one
Install, by operating system
Same three steps on every OS — download, install Node, open a terminal in the unzipped folder. Only the command prefix changes.
Install Node.js LTS from nodejs.org, then unzip the Runner folder anywhere. Windows 11: right-click an empty spot inside the folder → "Open in Terminal". Windows 10: hold Shift, right-click inside the folder → "Open PowerShell window here". PowerShell requires the .\ prefix shown below.
.\start.cmd doctor
.\start.cmd verify
.\start.cmd backtest --symbol NVDA
.\start.cmd runSeeing "Windows protected your PC"? That's SmartScreen because the zip came from the internet — click "More info" → "Run anyway". Everything it does is in one readable file, playbook-runner.mjs.
Install Node.js LTS from nodejs.org, then drag the unzipped folder onto Terminal in your dock (or cd into it).
./start.sh doctor
./start.sh verify
./start.sh backtest --symbol NVDA
./start.sh runIf you see "Permission denied", run chmod +x start.sh once, then try again.
Install Node.js LTS from nodejs.org (or your distro's package manager, version 20+), then cd into the unzipped folder.
./start.sh doctor
./start.sh verify
./start.sh backtest --symbol NVDA
./start.sh runIf you see "Permission denied", run chmod +x start.sh once, then try again.
Prefer clicking? Double-click start.cmd (Mac/Linux: run ./start.sh with no arguments) for a small menu — verify, backtest, run, setup, doctor.
doctor checks Node, your config, your Alpaca keys (it actually connects), the market clock, price data and the playbook file — one line per check, with the fix. verify explains the playbook in plain English — for a purchased bot that means every book in the file: the 15m, 1h and 4h books, each with its entry rules, exits, side and version, plus the bot's own position limits. backtest shows how it would have traded a symbol recently, book by book and combined. run starts it trading — see the two paths below for what that means before and after you connect a broker.
What's in a purchased file
You get the bot's full rulebook set: all three adopted books for short, medium and long horizons, and the latest published rulebooks with Live-Sync. The stock scan runs on your machine with your own Alpaca keys, against the same list we use. The four Core bots' files are their whole rulebook (one book; use verify to check your file's interval). The System file holds all 15 setup definitions in a fixed hourly adaptation with shared risk settings, not the hosted account's per-strategy execution; Earnings Quality Trend acts only as an exit, as on the site. For the Weather and Super Bot bots only, their app-side account layers (volatility-targeted sizing and the hourly allocator; Super Bot also intraday posture) run in the Arena engine and are not in the file — the file says so in its own note.
What that looks like at the keyboard, with Runner 0.7.0 or later:
- verify prints "Full-bot bundle: 3 of 3 books present (15m, 1h, 4h)", then each book under its own heading — timeframe, side, version, last rewrite, entry rules, exits, stop, target, trail. The 4h book's bars are built on your machine from 1h bars, using stable session-aligned slots (09:30 and 13:30), the same slots the site uses. Your Runner acts only on completed bars. A Core or System file prints as a single book.
- run trades all of the books in one account and one position pool, bounded by the bot's own limits (max positions, per-book cap, short exposure). The book that opens a position owns its exits; your runner.config.json caps can only tighten the bot's, never loosen them.
- update (and run's own daily check) treats a change to any one book as a new version, and says which books changed.
- The scan: give setup your Alpaca keys (paper or live — the free IEX feed comes with every Alpaca account) and each cycle the Runner ranks the same list of roughly 1,000 US stocks we scan, on your machine, and studies the shortlist. Without keys it prints scan: no Alpaca keys — using the universe ladder on every cycle: that means it is choosing from the smaller list built into the file instead of scanning the whole market. Adding keys enables the local stock scan; the hosted AI, news research and learning services remain on the website.
Your own record starts the day you run it. No file reproduces a bot's public return: data timing, stock selection, account limits and fills can differ. The current customer download is Runner 0.7.1; scan-selection corrections in the 0.7.2 candidate are not yet a customer release.
Two ways to start
Reading and testing a playbook is always free, with or without an account. Only trading one — even in paper mode — needs a broker connected. Pick one path; you can move from the left to the right at any time.
Try without an account
No sign-up, no keys, no card. run defaults to dry-run: it watches real prices and prints what it would do — no order ever reaches a broker. This trades the bundled starter demo unless you drop a purchased .playbook.json file into the folder.
.\start.cmd run (Mac/Linux: ./start.sh run)
Watch a full session before you decide whether to go further.
Connect a paper account
Sign up free at alpaca.markets, switch the top-left toggle to "Paper" (fake money), then "API Keys" → "Generate" — copy the Key ID and Secret (the secret is shown once).
.\start.cmd setup (Mac/Linux: ./start.sh setup)
setup asks for those keys, connects to Alpaca on the spot to catch a typo immediately, and writes runner.config.json with "mode": "paper". Real order flow, fake money — stay here as long as you like. With keys in place the Runner also runs the stock scan on your machine each cycle, against the same list we use.
One Runner per brokerage account
Paper or live, use one installation, one ledger and one running process per brokerage account — including the free starter. Do not connect a second bot or make manual trades in that account. Three license activations allow separate accounts, not three Runners sharing one account.
Brokerage execution requires an internet check with our account-binding service at startup, including halt and reconcile. It sends hashed account and ledger-path identifiers, random installation and ledger identifiers, and a random binding token — never your brokerage keys, account number, balances, positions, trades or literal folder path. If this check fails, execution does not start.
Keep your original state file, its path, and your user profile’s .playbook-runner/accounts ownership record. Back them up securely and stop the Runner before upgrading. A different ledger or installation is refused even while the original is offline. There is no automatic account transfer or reset: contact support before moving machines or replacing lost records. Do not delete state to clear an error. Stopping the program does not cancel orders or close positions; check your broker when trading is halted.
How it trades
It checks the market at its configured interval, and only while the US market is open.
It has to be running to place new trades. A sleeping laptop means no new trades — it doesn't catch up later. Want it running around the clock? Put it on a machine that stays on, like a spare mini PC or a cheap cloud server.
It never invents a trade. It follows the rules written into your playbook file, nothing more — every book in it, on that book's own bars.
It reads your account value from your broker every cycle and sizes each trade within your configured caps. Long entries can use fractional shares; short entries use whole shares and require explicit broker approval and available borrow. A smaller account may have to skip an entry that cannot fit its caps.
After an entry fills, it attempts to place protective stop orders at your broker. Placement can fail, and a stop does not guarantee an execution price. Resting broker orders can remain active while the Runner is off; fractional-share protection can expire at the end of the day. On restart, the Runner checks its recorded orders and positions before submitting anything new. If it cannot establish what happened, it stops and reports the problem rather than guessing.
While run is going it checks for a new playbook once a day and swaps it in between cycles; you don't have to do anything. update still works by hand.
Settings you can change
These live in runner.config.json, next to start.cmd.
| Setting | What it means | Default | Allowed range |
|---|---|---|---|
| maxPositions | How many positions it can hold at once | 8 | 1–20 |
| maxPositionPct | Max size of one position, as % of your account | 10% | 1–25% |
| dayLossHaltPct | Stops trading for the day past this loss | 2% | 0.5–10% |
| cycleMinutes | How often it checks the market | 15 min | 5–120 min |
| mode | dryrun, paper, or live | dryrun | — |
The Runner refuses any edit that would make it riskier than these caps — it will not quietly loosen a limit you set.
Advanced: trading real money
Only open this once you've watched the Runner in dry-run or paper mode and trust what it's doing. Everything below only applies to "mode": "live" — dry-run and paper never touch a real account.
Activation, for a purchased playbook
The bundled starter never needs this. A playbook you bought needs activating on this computer before it will trade — reading it (verify, backtest, dry-run) is always free:
.\start.cmd activate (Mac/Linux: ./start.sh activate)
Activation sends your email, license key, and a device id computed from this computer — never your broker keys or trades. Up to 3 computers per license; free a license slot with deactivate on an old one. A buy-once activation token does not expire; a Live-Sync subscription refreshes through updates. Brokerage execution separately requires the account-binding startup check. Deactivating a license does not move that binding to another computer.
Getting a live Alpaca key
At alpaca.markets, switch the top-left toggle to "Live" instead of "Paper" before generating keys. A live key is a completely different pair from a paper key — the Runner's doctor command tells you which one it sees. Alpaca allows one live account per person, so keep only the money you want the Runner to manage there and hold other investments at a different broker.
What happens when you set mode to "live"
Every time live mode starts, the Runner first connects to your real account and shows the real numbers on screen — equity, dollars per position, and the day-loss halt in dollars — before it places a single order:
Safeguards that stay on in live mode
- The Runner attempts protective stop placement after fills and checks for conflicting orders before replacement. Broker rejection, expiry and price gaps remain risks; a stop is not guaranteed protection.
- Position sizes are capped using account data re-read from the broker. Buying power, borrow availability and prices can change before execution; the broker can still reject an order.
- maxPositions × maxPositionPct may never exceed 100% of your account — that would be margin, and the Runner refuses that config.
- It only trades while the US market is open; a closed-market cycle only checks on positions you already hold.
- Heads-up for accounts under $25,000: US brokers apply the pattern-day-trader rule (4 same-day round trips in 5 business days) to margin accounts — the Runner warns you once a day when it could apply.
- It never touches orders or shares it did not create itself.
Trading involves risk of loss. Nothing on this page is investment advice; past results do not predict future results. Full terms: Terms of Use & Sale and Risk Disclosure.
Stopping it
Press Ctrl+C to stop the Runner. This does not close your positions or cancel broker orders. Stop placement can fail, fractional-share stops can expire at the end of the day, and price gaps can change the exit price. Check your positions and remaining orders at your broker; do not assume they are protected.
To close positions manually, stop the Runner and use your broker's close-position action. Closing a long position sells shares; closing a short position buys to cover. Check existing exit orders first, then confirm fills and remaining orders at your broker before submitting another closing order.
Only one Runner can trade a folder at a time. A second copy in the same folder will say so and stop. If the first one crashed and left a lock behind, delete runner-state.json.lock and start again.
If something's wrong
Run .\start.cmd doctor first — it names the problem and the fix in one line.
Still stuck? Use the chat bubble in the corner of any page on this site, or the Contact page.