Getting started

The client is free. It runs on your computer. It does not hold your money.

What an API key is

An API key is a credential your exchange gives to a program. The Exchange wizard requires a native OS keychain (Apple Keychain / Windows Credential Manager / Secret Service / libsecret) to store the key and secret. It refuses plaintext and nonpersistent backends; krellbot.dev never receives the exchange credentials.

There is no automatic file fallback when a keychain is unavailable. The legacy engine can read a file you explicitly configure with KRELLBOT_<VEN>_KEYFILE, after a restrictive POSIX file-mode check or an explicit Windows acknowledgement; the wizard never writes to that file. krellbot doctor reports the detected backend and readiness.

Credential-source precedence when the engine loads a key is a complete KRELLBOT_<VEN>_KEY and KRELLBOT_<VEN>_SECRET environment pair, then the keyring (including a wizard-stored pair), then an explicitly configured keyfile if no keyring entry exists. A partial environment pair is an error. Wizard status cannot tell you which credential a later trade will use.

Turn trade on. Turn withdraw off.

You need a Kraken or Coinbase account before a pack can place an order. You do not need one to read these docs or to install the client.

When you create the key:

Trade permission on.
Withdraw permission off.

Paper is the path to use

Paper mode runs a pack end-to-end against a local fill simulator. No order leaves your machine. No exchange API call is made. No license is required. Start there.

When this release ships: a local four-step wizard

When a release publishes a frozen binary for your chip / OS combination (the install endpoint stops returning 503), krellbot ui renders an optional first-run wizard in the browser at the loopback URL the CLI prints. The four-step flow is Welcome → Security → Exchange → Next:

Welcome. What the engine is, and what the operator approves in this install.
Security. Read-only local trust posture from trust_snapshot — keychain backend, $KRELLBOT_HOME path and POSIX mode, loopback bind, the live_arm_ui_allowed = False rail.
Exchange. One credential-bearing POST to the local dashboard for the venue you choose (Kraken or Coinbase). Its handler sends an authenticated HTTPS permission request to that venue, then stores only a verified trade-only pair in the native OS keychain. The credential does not reach krellbot.dev, is not echoed back, and is not written to the journal or to any receipt.
Next. Enter the dashboard on explicit POST.

The wizard is server-rendered and works without JavaScript. The status shown on a later GET is HISTORICAL — "last stored through wizard at <timestamp>; current key presence not checked" — never a live-connection claim. The dashboard GET never reads the API key or secret and never probes the venue.

The keyring write is two slots and is NOT atomic. On a slot write failure, the wizard fails closed (no green light), attempts a best-effort restore of the prior pair, and surfaces the failure. CLI-side rotation is not detectable from the browser without a credential read, so the GET status is always HISTORICAL.

Until that release ships, use the CLI path shown below. Unlike the wizard, krellbot keys add stores to the configured keyring without probing permissions; run krellbot keys check kraken afterward. There is no automatic plaintext-file fallback.

Live requires typing `LIVE`

Live arms a pack against the real venue. The first live arm on an install asks you to type LIVE exactly. KRELLBOT_ENABLE_LIVE=1 must be set, and the key must be trade-only. See Live trading for the full gate. Live arm from the browser wizard is 403 by construction — the typed LIVE confirmation is a CLI-only path. The free path today is the dashboard, the CLI, and krellbot doctor.

Install the free client

The one-line install commands on the home page are the real installer endpoint. They are release-gated:

Until a release artifact is published and the release manifest is wired up, the endpoint returns 503 installer disabled. A 503 is the expected response on hosts whose chip / OS combination does not have a published release yet — it is not a bug.
The endpoint refuses to download when the local machine's chip (x86_64 / arm64) has no entry in the manifest. Rosetta will not silently mask the mismatch; the installer prints an explicit refusal and exits non-zero.
The downloaded binary is SHA-256 pinned against the manifest. It is not code-signed, notarized, or Authenticode-signed in this release — see Security.

The branch installer is Python-free — Python is not a prerequisite on either macOS / Linux or Windows once it ships. Until a verified release artifact is published and the release manifest is configured, the live endpoint returns 503 and serves neither the new Python-free installer nor the retired Python-based one.

Where things go on disk

What	POSIX	Windows
Launcher you invoke	`~/.local/bin/krellbot`	`%LOCALAPPDATA%\Krellbot\bin\krellbot.cmd`
Frozen binary	`~/.local/share/krellbot/versions/<ver>/krellbot`	`%LOCALAPPDATA%\Krellbot\versions\<ver>\krellbot.exe`
Prior launcher (rollback)	`~/.local/bin/krellbot.prior`	`%LOCALAPPDATA%\Krellbot\bin\krellbot.cmd.prior`
Engine data home (`$KRELLBOT_HOME`)	`~/.krellbot/`	`%USERPROFILE%\.krellbot\`

The launcher and the frozen binary are two different things. The launcher is a small shell wrapper that exports KRELLBOT_HOME and execs the frozen binary at the version the manifest pinned. The frozen binary is the engine.

PATH check

On POSIX the launcher lands in ~/.local/bin. That directory is not on $PATH on most distros. The installer prints the right next step when it finishes; in a new shell:

krellbot --version

If command not found, add a line to your shell rc and restart the shell:

export PATH="$HOME/.local/bin:$PATH"

Or invoke the launcher by absolute path:

$HOME/.local/bin/krellbot

Uninstall and data retention

Uninstall removes the launcher and the staged frozen binary:

curl -fsSL https://krellbot.dev/api/install?os=mac | sh -s -- uninstall

The engine's data home under $KRELLBOT_HOME is preserved across uninstall by default — the journal, receipts, armed-pack config, license cache, and nonsecret key-status history remain for a reinstall. To remove that data home, pass --purge-data:

curl -fsSL https://krellbot.dev/api/install?os=mac | sh -s -- uninstall --purge-data

OS keychain entries remain after either uninstall command, including --purge-data; remove them separately in your platform's credential manager if you want to erase saved exchange credentials. The installer removes the launcher and staged binary directories, and removes $KRELLBOT_HOME only with --purge-data. It does not touch unrelated files under $HOME.

Releases and update policy

A release is a frozen, SHA-256-pinned archive of the engine plus the full manifest the install endpoint serves. The launcher execs a frozen binary at a specific version path; rerunning the install command stages the new version aside, swaps the launcher atomically, and preserves the prior launcher at krellbot.prior on POSIX and krellbot.cmd.prior on Windows for manual rollback. The engine data home is never modified by an install or update.

Three-platform release artifacts (macOS / Linux / Windows, x86_64 and arm64 where applicable) are the release-gate promise. Until the matrix is built and the manifest wired up for every chip / OS combination advertised, the install endpoint returns 503 on the missing combinations — the home page says so explicitly.

What a pack is

A pack is a JSON file. The format is open. You can write your own and put it in ~/.krellbot/packs/. The client reads the file. It does not run code inside it.

The packs we maintain are a separate download. Those names stay off the public page. $39 a month downloads them.

krellbot setup <activation-key>

A pack you write does not need that key.

Adding an exchange key today (CLI path)

The CLI is the key-entry path until the frozen release above ships. Prepare a temporary file with two lines (API key, then secret); keep it private and remove it after a successful import. keys add writes to the configured keyring and checks the write, but does not verify exchange permissions. It does not automatically write a plaintext fallback file. krellbot.dev never receives the key.

krellbot keys add kraken --file ~/.config/krellbot/kraken.key
krellbot keys check kraken

keys add does not contact the venue. keys check probes the selected venue with an authenticated HTTPS request after the store and must report kraken: trade on, withdraw off before you treat the key as ready. If no keyring entry exists, a separately managed KRELLBOT_<VEN>_KEYFILE is a legacy read path, not the wizard's storage path. The browser's status is HISTORICAL only ("last stored through wizard at <timestamp>; current key presence not checked").

What a window is

A window is the dates the chart covers. A return without those dates is not a result you can read.

What a drawdown is

A drawdown is how far the result fell from a high point before it recovered. A high return with a large drawdown is still a large drawdown.

What it will not do yet

The live tick path is wired: the CLI builds a real KrakenVenue or CoinbaseVenue in venue_for_tick, and the tick loop in src/krellbot/run/__init__.py calls the venue adapter order methods (place_entry_with_stop, place_exit, place_stop) when KRELLBOT_ENABLE_LIVE=1 and a trade-only key is stored. The code path can place real orders. What is not done in this build:

The path is not verified against a production account. The wiring is in place and unit tests exercise the adapter order methods, but no order from this build has been observed reaching a live Kraken or Coinbase account. Treat the live tick path as wired-but-unobserved: it may send a real order, fail at the venue, or be refused for reasons the local tests do not cover.
Paper ticks are the only ticks with a tested, deterministic fill.

← docs