Development Setup

First-time setup for a new developer. Should take ~30 minutes if accounts are pre-provisioned, longer if you need to create them.

Prerequisites

Node.js 24 LTS (nvm install 24 && nvm use 24)
pnpm 9+ (corepack enable && corepack prepare pnpm@latest --activate)
Git
Supabase CLI (brew install supabase/tap/supabase on macOS, or download from https://supabase.com/docs/guides/cli)
Fly CLI (brew install flyctl or https://fly.io/docs/flyctl/install/)
Vercel CLI (optional, pnpm i -g vercel) — handy for env var management

Accounts you'll need

Account	Why	Free tier OK?
Vercel	Web app hosting	Yes (Hobby)
Supabase	DB + Auth	Yes (Free)
Fly.io	Live runner hosting	Yes (limited)
Hyperliquid (mainnet wallet)	For live integration (testnet deprecated — ADR-0015). Start with small balance.	Free to create; trade with what you fund
AI Gateway (via Vercel)	Model routing — $5/mo free credits per team	Yes

For team development, ask the lead for invitations to the shared Supabase + Vercel projects rather than creating your own.

1. Clone and install

git clone <repo-url> agentic-trading
cd agentic-trading
pnpm install

2. Environment variables

cp .env.example .env.local

Fill in the values per the comments in .env.example. See docs/security/secrets.md for what each one is and where to get it.

For local dev, the minimum to boot the web app:

SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_URL=...
SUPABASE_ANON_KEY=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...
AI_GATEWAY_API_KEY=...

The rest are needed for specific features (Fly for deploying live, CryptoPanic for news ingest, etc.) — add as needed.

3. Link to Supabase project

supabase login
supabase link --project-ref <dev-project-ref>

Get the project ref from the Supabase dashboard URL: https://supabase.com/dashboard/project/<this-bit>.

4. Apply migrations

supabase migration up

This applies every migration in packages/db/migrations/ against the linked project.

If you're starting from scratch (own Supabase project, not shared), this populates the schema. If you're sharing the team dev project, this is a no-op.

5. Run the web app

pnpm dev

Open http://localhost:3000. You should see the landing page. Sign up with a test email; check your inbox for the magic link.

6. (Optional) Seed local data

pnpm seed

Creates: a demo Skill, some recent bars for BTC, a few news items, one inactive deployment. Lets you click around without needing to wait for data ingest.

7. (Optional) Run a simulation locally

pnpm sim --skill <skill-id-from-seed> --from 2026-04-01 --to 2026-05-01 --symbol BTC --interval 5m

The sim runs in-process, writes snapshots to the dev DB, and prints the report path on completion.

8. (Optional) Run the live runner locally

Useful for end-to-end testing of the live path. Use the paper broker for development; only switch to hyperliquid-mainnet when intentionally validating real-money flow (testnet was removed — ADR-0015).

First, create a deployment via the UI (or directly in the DB) with broker_kind='paper' (or hyperliquid-mainnet for the real-money path, with a small funded wallet). Note the deployment id.

DEPLOYMENT_ID=<uuid> pnpm --filter live-runner dev

The runner will tick on the Skill's schedule. You can send commands by inserting rows into agent_commands in the Supabase dashboard, or by clicking the buttons in the web UI.

Repository layout (quick reference)

apps/
  web/              # Next.js — UI + control API + chat agent
  live-runner/      # Node service — Fly per Skill
packages/
  skill-schema/     # zod types
  agent-runtime/    # runSkill() — pure logic
  tools/            # built-in + MCP tools
  execution-engine/ # safety boundary
  brokers/          # paper / hyperliquid adapters
  simulator/        # replay loop
  data-ingest/      # cron-driven bars/news/funding pulls
  db/               # Supabase client + migrations
  shared/           # shared types
docs/               # ← you are reading these
infra/              # Fly toml, Supabase config, vercel.ts

Common commands

Command	What it does
`pnpm dev`	Run web app in dev mode
`pnpm build`	Build all apps and packages
`pnpm lint`	ESLint
`pnpm typecheck`	TypeScript across all packages
`pnpm test`	Run all unit tests
`pnpm --filter <pkg> dev`	Run a single package in dev mode
`pnpm --filter <pkg> test`	Run tests for a single package
`pnpm sim --skill <id> --from <d> --to <d>`	Run a simulation locally
`supabase migration new <name>`	Create a new migration file
`supabase migration up`	Apply pending migrations
`supabase db diff`	Show pending schema changes
`supabase gen types typescript`	Regenerate `packages/db/types.ts`
`fly deploy -a agentic-live-runner`	Deploy live runner (CI normally does this)

Troubleshooting

`pnpm install` fails with peer dependency warnings

Ensure you're on pnpm 9+. Older versions handle peer deps differently.

Check Supabase dashboard → Authentication → Logs. Often a typo in the email or rate-limiting.

Local web app can't talk to Supabase

Verify the NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY are set in .env.local
Restart pnpm dev after env changes (env is read once at boot)

Migrations fail with "permission denied"

You're probably linked to the prod project. Re-link to the dev project: supabase link --project-ref <dev-ref>

Live runner exits immediately

Check it can reach Supabase + AI Gateway with its env vars
Verify the DEPLOYMENT_ID exists and is in a valid status
Check agent_logs for the deployment — the runner writes a startup log

AI Gateway 429 / rate limit

You probably blew through the $5 free tier. Top up or use a BYOK Anthropic/OpenAI key.

Editor setup

VS Code with extensions: ESLint, Prettier, Tailwind CSS IntelliSense, "Pretty TypeScript Errors"
TypeScript version: use workspace TypeScript (>TypeScript: Select TypeScript Version → Use Workspace Version)
Path completion: TS paths defined in root tsconfig.json; should "just work"