Getting Started

Keel is a quantitative crypto trading platform driven from your terminal or your AI agent. The default install is local — strategies live in your filesystem, your agent reads + edits them directly, backtests run against Keel's cached price + funding data on Hyperliquid.

See it working first: Verified Keel backtest of a funding-carry strategy — Sharpe 2.17, +79.6% return, -9.7% max drawdown, 2024-08-15 → 2026-04-30 on Hyperliquid perps.

Two commands, then talk to your agent

pipx install keel-trade               # or: uv tool install keel-trade
claude mcp add keel -- keel mcp serve  # register the stdio MCP with Claude Code

Open Claude Code and say:

"Connect to Keel, then backtest a carry strategy."

Claude calls keel_auth_login (browser opens — sign in, close the tab), then keel_strategy_compose + keel_backtest_run. You're done. No terminal-side login dance, no ~/.keel/config.yaml to inspect.

What the agent does for you

Each tool returns a share_url you can click to see the tearsheet in your browser.

1. Install

pipx install keel-trade      # or: uv tool install keel-trade

Requires Python 3.11+. pipx and uv both work — pipx is more common, uv is faster. The package ships with the Keel DSL validator, component catalog (182 components), and the MCP server bound into the keel binary.

Verify:

keel --version
# keel, version 0.4.2

2. Register the MCP for your agent

# Claude Code
claude mcp add keel -- keel mcp serve

# Cursor — add to .cursor/mcp.json:
{
  "mcpServers": {
    "keel": { "command": "keel", "args": ["mcp", "serve"] }
  }
}

The agent host launches keel mcp serve as a child process and talks to it over stdin/stdout. You do not need to run a daemon, open a port, or start a separate service. No login needed yet — the next step does that from inside Claude.

Agent Setup has the full matrix (Windsurf, Continue, Cline, OpenAI Codex, generic MCP client).

3. Sign in — from inside Claude

Open Claude Code (or your MCP-capable agent) and say:

"Connect to Keel."

Claude calls the keel_auth_login MCP tool. Your default browser opens to app.usekeel.io/oauth/connect, you complete the OAuth 2.1 + PKCE consent, and tokens land in ~/.keel/config.yaml. You stay logged in for 30 days — access tokens refresh transparently before each request.

For live-trading scope (deploy / pause / stop strategies on Hyperliquid), say:

"Connect to Keel with live trading."

Claude calls keel_auth_login(scope="live") and the "Include live trading" checkbox is pre-checked on the consent page. Live trading also requires you to arm your local machine — defense in depth. See keel arm live --help.

Logging in from a terminal

If you'd rather skip the MCP-driven flow and authenticate before registering the MCP, the same OAuth ceremony is one CLI command:

keel auth login

For headless environments (CI, SSH, GitHub Codespaces, WSL without port forwarding) where the CLI and your browser are not on the same machine, use:

keel auth login --key <token>
# Token from https://app.usekeel.io/settings?tab=api-keys

4. Verify

keel status

Shows your identity, org, plan, entitlements, and the scopes your session has — also lists every MCP tool currently exposed under your KEEL_TOOLSETS. If anything looks off, run keel auth logout and try again. From inside Claude, the equivalent is "What's my Keel status?" (which calls keel_status).

5. First strategy + backtest

From your agent, ask:

"Create a funding-carry baseline, validate it, save it, then backtest 2025-06-01 through 2026-02-01."

The agent should follow this tool sequence:

CLI equivalent for an existing strategy.py:

keel strategy compose --source-file strategy.py --dry-run --format json
STRATEGY_ID=$(keel strategy compose \
  --source-file strategy.py \
  --name my-first \
  --format json | jq -r '.strategy_id')
BT_ID=$(keel backtest run "$STRATEGY_ID" \
  --start-date 2025-06-01 \
  --format json | jq -r '.run_id')
keel backtest watch "$BT_ID" --format json
keel backtest summarize "$BT_ID" --format json

Open the returned hero_url or share_url in your browser for the rich tearsheet.

Omit --end-date to run through today's UTC date. Pass it only when you need a fixed historical window.

Next steps

• Step-by-step CLI walkthrough — every command with annotated output
• Agent Setup — Claude Code, Cursor, Windsurf, Codex configs + skills
• CLI Reference — every command grouped by domain
• Web app alternative — visual strategy builder + AI editor at app.usekeel.io

Going live

Once you have a backtested strategy you want to run on Hyperliquid:

# Connect or manage Hyperliquid accounts in the web app:
# https://app.usekeel.io/settings/accounts

# Arm your local machine for live trading (second lock)
keel arm live set --account <account-id>

# Preview deployment first; no orders are sent
keel live deploy <strategy-id> --account-id <account-id>

# Actually deploy only after explicit confirmation
keel live deploy <strategy-id> --account-id <account-id> --no-preview

Live trading requires:

1. OAuth live scope on your CLI token (keel auth login --scope live)
2. Local arming via keel arm live set (per-machine)

Both gates are required. The second prevents an exfiltrated token from deploying live trades — the attacker would need filesystem access to your machine too.

Plan limits

Your current plan, entitlements, scopes, and exposed toolsets are shown by keel status. Sign up or manage billing at app.usekeel.io.