Getting started

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.

⬇ Download the Runner — free, no card, no sign-up

One zip (about 80 KB). It contains the Runner app plus a bundled starter playbook you can trade in dry-run immediately — no account, no email, no license key.

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
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 run

Seeing "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 run

If 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 run

If 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. backtest shows how it would have traded a symbol recently. run starts it trading — see the two paths below for what that means before and after you connect a broker.

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.

Path A

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.

Path B

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.

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 every 15 minutes, 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.

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:

It then requires you to type, in CAPITALS, exactly I UNDERSTAND THE RISK at the keyboard. Starting it from a script or a scheduler with no keyboard attached is refused outright ("cannot confirm live mode without a keyboard") unless you pass --i-understand-the-risk on the command line yourself — there is no way to reach live mode by accident.

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. Any time. Your open positions stay protected — each one already has a real stop order sitting at your broker.

To flatten everything by hand, sell the positions in your Alpaca dashboard and cancel their stop orders.

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.

Back to the Playbook store