> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hellonear.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```sh theme={null}
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 |

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.