Run locally

Run the engine, backend and web app on your own machine.

Needs Node ≥ 24.22.1, Bun, Docker (OrbStack on macOS) and a NEAR AI Cloud API key.

docker compose up -d postgres                       # Postgres 17 + pgvector, capped at 1 CPU / 512 MB

cd engine && cp .env.example .env                   # set NEARAI_API_KEY and ENGINE_API_KEY
bun install && bun run dev                          # http://localhost:4100/v1/health

cd ../apps/be && cp .env.example .env               # same ENGINE_API_KEY; SECRETS_MASTER_KEY=$(openssl rand -base64 32); DEMO_MODE=true
bun install && bun run migrate && bun run dev       # http://localhost:4000/v1/health → {"ok":true,"engine":true}

cd ../fe && NEXT_PUBLIC_API_URL=http://localhost:4000 bun run dev   # http://localhost:3000

Payments also need DEMO_OUTLAYER_API_KEY (an OutLayer wallet’s agent key) in apps/be/.env. docker compose stop when done.

Tests: bun run test in engine/ and apps/be/ (integration: real NEAR AI + local Postgres), bun run test in apps/fe/, cargo test in sc/ (unit + local NEAR sandbox). Load: k6 run engine/load/chat.js, k6 run engine/load/workflow.js, bun run load in apps/be/. Each package has a GitHub Actions workflow.

Folder	What
engine	AI engine: Mastra 1.81 on NEAR AI Cloud, skills, tools, memory, Visual Builder, Autopilot, verification
apps/be	Backend API: NEP-413 sign-in, Minds, OutLayer wallets, approvals, secrets, connections, Telegram, Postgres
apps/fe	Web app (Next.js 16, NEAR Connect with Meteor first)
apps/landing	Landing page
sc	Mind registry contract (Rust near-sdk 5.29)
docs	API contract between web app, backend and engine
design	Design tokens, screens and Mind characters
deploy	Hosted demo: systemd units, deploy.sh, automatic deploy after a merge

---