​
Quickstart

​
Prerequisites

ToolWhy
Python 3.11+The agent is a FastAPI process. 3.11 is the floor.
Claude Code (npm install -g @anthropic-ai/claude-code)The chat UX. Optional if you only want REST.
MangroveAI API keyFree at mangrovedeveloper.ai. dev_... or prod_.... The setup script will prompt for it.
VSCode (recommended)Universal editor + integrated terminal that behaves the same on macOS, Linux, Windows.
Git for Windows (Windows only)So *.sh scripts work via Git Bash. Set VSCode’s default terminal to Git Bash.
Docker is optional — see the alternate install below. Bare-metal is primary because the keyring library can reach your OS keychain directly when the agent runs natively. One command. It seeds your config (prompts for the API key), creates a venv, pip-installs dependencies, starts uvicorn in the background, registers the MCP server with Claude Code, and verifies /health. 
git clone https://github.com/MangroveTechnologies/mangrove-agent.git
cd mangrove-agent
./scripts/setup.sh
First run takes ~60s. Re-runs are idempotent — the script detects what’s already done and skips. When it finishes:
  • Agent runs at http://localhost:9080 (pid in agent-data/bare.pid, logs in agent-data/bare.log). Bound to 9080 externally because :8080 is commonly squatted by VSCode Helper.
  • ./scripts/verify_quickstart.sh --bare passes — the tool catalog returns the expected set.
  • Claude Code’s MCP registration now knows about mangrove-agent.

​
Useful flags

./scripts/setup.sh --yes --api-key dev_xxx   # fully non-interactive (CI / scripts)
./scripts/setup.sh --foreground              # run uvicorn in your terminal (Ctrl+C to stop)
./scripts/setup.sh --no-mcp                  # skip Claude Code registration
./scripts/setup.sh --no-verify               # skip the post-start verify pass
./scripts/setup.sh --docker                  # use Docker instead of bare-metal

​
Docker (alternate)

git clone https://github.com/MangroveTechnologies/mangrove-agent.git
cd mangrove-agent
./scripts/setup.sh --docker
State persists in the ./agent-data/ directory (bind-mounted into the container). The directory mount avoids the macOS / Windows single-file bind-mount staleness that previously ate DB rows after rebuild. The container cannot reach your OS keychain, so the Fernet master key lives in ./agent-data/master.key (chmod 600, gitignored).

​
Your first paper strategy (no wallet, no funds)

Start Claude Code in the repo directory. The agent runs a short platform tour — status, list_tools, get_market_data, kb_search, search_reference_strategies — then offers to help you build a strategy.
“Build me a momentum strategy for ETH on 1h. Use a reference.”
The agent searches curated reference strategies, picks a candidate, builds it, backtests with a timeframe-appropriate lookback, and reports PASS / MARGINAL / FAIL against six thresholds.
“Promote it to paper.”
Schedules the strategy on a cron at the strategy’s timeframe. Evaluations fire, paper fills get logged. No funds at risk.

​
Going live (optional — needs funds)

Wallet setup and live trading are in Chapters 06 and 07 of the tutorial. Summary:
  1. Create or import a wallet. create_wallet returns a vault_token, not the plaintext.
  2. Save the secret off-agent. ./scripts/reveal-secret.sh <vault_token> prints to your terminal once. Put it in your password manager.
  3. Flip the backup gate. ./scripts/confirm-backup.sh <address>. execute_swap and update_strategy_status -> live refuse on wallets without this flag.
  4. Fund the wallet with 1-5 USDC on Base.
  5. Promote the strategy to live. Allocation block requires confirm=true and slippage_pct <= 0.0025.
Live evaluations fire on the same cron. When the strategy decides to trade, the mangrovemarkets SDK routes the order through 1inch, the agent decrypts the wallet’s secret in-process, signs the transaction, broadcasts it, and zeroes the secret. The SDK never sees the key.

​
Running tests

docker compose exec app pytest tests/
# expect: 239 passed, 2 skipped (opt-in live-swap tests)
Opt-in live swap tests: 
# Testnet (Base Sepolia)
ENABLE_SEPOLIA_TEST=1 BASE_SEPOLIA_PRIVATE_KEY=0x... \
  pytest tests/e2e/test_live_swap.py::test_sepolia_live_swap

# Mainnet — real funds; the project default test value is 0.10 USDC
ENABLE_MAINNET_TEST=1 BASE_MAINNET_PRIVATE_KEY=0x... \
  pytest tests/e2e/test_live_swap.py::test_mainnet_live_swap

​
Deployment

Local-only for v1 (Docker Compose). Cloud deployment (Cloud Run + persistent storage + Cloud SQL) is on the roadmap, not shipped.