First Steps

This is the shortest path from a fresh clone to a working FourIA environment. Each step links to deeper documentation.

1. Prerequisites

Tool	Why	Install
Bun	Runtime, package manager, and test runner for all TypeScript packages.	https://bun.sh/
Node.js 22	Required by some dependencies.	https://nodejs.org/
Docker	Builds and runs the Sandbox container image locally.	https://docs.docker.com/get-docker/
Cloudflare account	Workers Paid plan for Sandbox containers.	https://dash.cloudflare.com/
Nix (optional)	Root/Elixir shells and the docs site toolchain.	https://nixos.org/download

2. Clone and install

git clone <repo-url> fouria
cd fouria
bun install
bun run build:all

build:all builds the shared packages (cost calculator, unified-billing plugin, moltlazy) and the Worker dashboard bundle.

3. Configure local environment

cp apps/fouria/.dev.vars.example apps/fouria/.dev.vars

# and CF_AI_GATEWAY_GATEWAY_ID at minimum.

See Platform → Environment Variables for the full reference.

4. Run the services

# Terminal 1 — Worker dashboard (Vite, hot reload on :8787)
cd apps/fouria && bun run dev

# Terminal 2 — Worker backend (:8788)
cd apps/fouria && bun run dev:worker

For the Lerma dashboard, see Lerma → Overview and its DEPLOY guide.

5. Verify your setup

# TypeScript packages
bun run lint
bun run test

# Elixir workspace (inside `nix develop .` from the repo root)
mix deps.get
mix workspace.run -t deps.get
mix check

6. Build the docs site

The site you are reading is built from the repo markdown with Zola:

cd webs/fouria-docs
nix develop --command bun run docs:sync   # repo markdown → Zola content
nix develop --command zola build          # static site → webs/fouria-docs/public
nix develop --command zola serve          # live preview

7. Go deeper

• Platform architecture — how the pieces fit together.
• Development guide — component reference and workflows.
• Testing guide — unit, integration, and E2E suites.
• Contributing — TDD, pre-commit, and PR expectations.