Last updated 29 July 2026

Getting started

Install AlgoSutra on your own machine and reach a running console. About 30 minutes, most of it unattended, and nothing trades live until you explicitly say so.

01What you need

Software	Docker, and Docker Compose 2.20 or newer. The installer offers to install Docker for you if it is missing.
Machine	Linux, macOS or Windows — anywhere Docker runs. One machine. No cloud account required, and nothing of yours leaves it.
Disk	Tens of gigabytes. The first build takes roughly 20 minutes on a cold machine; later starts take seconds.
Broker	Optional to begin with. AlgoSutra runs in paper mode with no broker connected at all.

You do not need to decide anything irreversible to try it. Paper mode is the default and the only implicit mode — going live is a separate, deliberate sequence described further down.

02Install

Unpack the release you were sent, then run one command:

cd algosutra
./install.sh

That is the whole installation. The rest of this section is what it will ask, so you can decide your answers in advance rather than mid-prompt.

Add --dry-run to see every path it would resolve — including where your container storage actually lives — without changing anything on disk.

03The questions it asks

1 — A base directory. Where AlgoSutra keeps the data you can see; your backups live here. It defaults to the folder containing the checkout.

One honest caveat: container volumes and image layers do not follow this setting — your container engine decides where those live, and they are the large ones. The installer checks, tells you, and offers to relocate them. Saying no is fine.

2 — Where backups land. A folder on your own filesystem, not a hidden Docker volume, so you can open it, copy it to a NAS or a USB stick, and see how big it is. The most useful answer points at a different physical disk — that is the only kind of backup that survives losing the disk your database is on.

It must be a folder AlgoSutra owns. The platform takes ownership of that directory and re-permissions it on every start, so it has to contain backups and nothing else. Point it at a folder holding your own files and the installer refuses by name rather than taking them over.

3 — An off-host backup key, if you want one. Backups on the same disk as the database survive a bad upgrade; they do not survive losing the disk. If you want encrypted copies sent to S3-compatible storage or over rsync, the installer generates a keypair now.

4 — Registration. You are offered a name for your install, then an email, a signup code, and the licence agreement to accept by typing accept. Leave the email blank to skip: an unregistered install is fully working and fully unenforced.

04Two things you cannot get back

The backup encryption key is printed once and written nowhere. Not to a file, not to the database, not to any artefact the platform produces. That is deliberate — a machine that could decrypt its own off-site backups has not moved the risk anywhere.

Put it in a password manager or on paper. Lose it and the off-host copies are unreadable by everyone, ourselves included. Your local backups are unaffected.

The operator console password is shown once, in a box near the end of the install. It is stored only as a hash. There is no reset link and no support channel that can recover it — losing it means reinstalling. Copy it before you close the terminal.

05Your first login

The installer brings everything up and prints your addresses. On a default install they bind to localhost only:

Operator console	`http://127.0.0.1:43001` — where you will spend your time
Dashboard API	`http://127.0.0.1:48443/healthz` — liveness, for scripts
Grafana	`http://127.0.0.1:43000` — dashboards
Prometheus	`http://127.0.0.1:49090` — raw metrics

Day to day, use ./start.sh and ./stop.sh rather than raw compose commands — they bring services up in dependency order and refuse a few configurations that look fine and are not.

06Connecting a broker

AlgoSutra supports eight Indian brokers: Zerodha, Dhan, Upstox, Angel One, Fyers, Kotak Neo, Groww and 5paisa. Credentials go in .env.broker, which never leaves your machine.

Running with none is a supported state — the market-data chain boots idle and the console works. Add brokers when you are ready.

Two things catch people out.

Each broker needs a redirect URI registered on your own broker developer app, pointing back at your install. The console's broker panel shows the exact address to paste.

After editing .env.broker you must re-stage it, or the platform keeps using the previous copy and rejects credentials that look correct in the file:

docker compose up -d --force-recreate broker-creds-init connect

The Admin page reports each broker's live session state — session live, session live · no feed, or session down — separately from whether credentials are merely saved. Those are different facts and the console keeps them apart, because a broker whose session died hours ago should not read as connected.

07Backups, and what they are worth

Backups are not a scheduled job. The platform maintains an invariant instead: the newest complete backup is never older than N hours. A machine powered off overnight backs up when it returns rather than silently skipping a day.

backup.rpo_hours	Default 24 — how stale the newest backup may get before one is taken.
backup.keep	Default 1 — how many complete backups to retain.

Both are changed in the console under Admin, and apply within seconds without a restart.

Consider raising backup.keep. At 1 you have no recovery window: damage you notice a week later is already in your only backup. Old backups are deleted only after a new one completes, so there is never a moment with none — but one is one.

Restoring is a documented, deliberate procedure rather than a button. The platform also ships a restore drill that restores a backup into a throwaway database and verifies it — so you can find out whether your backups work before you need them to.

08Writing a strategy

Your strategies live in strategies/ — a directory you own, mounted into the platform. One strategy object runs in backtest, paper and live; you do not rewrite it per venue.

You can test one with no broker, no market data and no other service running:

docker compose run --rm --no-deps strategy-runner \
    python /app/strategies/my_strategy/check.py

If it emits no orders, that is a real answer rather than a broken install — a strategy that decides on bars needs more than one tick before it has an opinion.

There are also 17 ready-made options templates — iron condors, verticals, straddles, calendars and more. One line picks the shape; every parameter lives in strategy.yaml, and a mistyped one is refused with the allowed names rather than silently defaulted.

09How live trading is prevented

Paper is the default and the only implicit mode. Going live is not a toggle: it needs an environment capability flag, separately-named live credentials, a per-strategy registry step, and a short-lived arming token that does not survive a restart. Miss any one and the platform stays in paper.

Kill switch	One click from any page, one command from the CLI. Halts the order path immediately; turning it back off is the deliberate direction.
Stale data	Treated as a fault, never as a price. The platform shows Disconnected and halts dependent strategies rather than trading on old ticks.
Risk gates	Every order passes a fixed cascade of pre-trade checks. There is no bypass.
Arming expiry	Live arming is short-lived and held in memory. An unexpected restart returns you to paper.

Nothing on this page arms live trading, and nothing about installing does either. Trading real money is a separate decision you make later, on purpose, more than once.

10If something looks wrong

The first install is slow. Expected — a cold machine builds every image from scratch, roughly 20 minutes.

No broker credentials. Not a fault. The chain boots idle by design and the console works.

A broker shows "session down". That is the panel doing its job. Most Indian brokers expire sessions daily and several use TOTP, so a login that worked yesterday can be refused today. Re-authenticate from the Admin page.

The installer refused your backup directory. It found files it did not create. That folder is chowned and re-permissioned on every start, so it must hold backups and nothing else. Point it at an empty one.

You lost the console password. It exists only as a hash and there is no recovery. Reinstall, or restore from a backup taken beforehand.

Anything else: contact us with your installation name and what you expected versus what happened. Never send broker credentials — we will never ask, and we could not use them.