Skip to main content

Quickstart

Get Bloom's monorepo running on your machine: the API offline, the dashboard against it, and the quality gate that everything must pass. Every command below is a target that exists in the repo today - the Makefile delegates to the pnpm workspace, so make <target> from the repo root and pnpm run ... in a package are the same thing.

The docker-compose dev environment was retired when the dev deploy moved to k3s/Helm: docker-compose.yml deliberately defines no services. Local runs go through the pnpm/Make targets below; the production API image builds from apps/server/Dockerfile.

Prerequisites​

  • Node.js 22 - the version the production image runs (node:22-alpine).
  • pnpm 10 - the repo pins pnpm@10.6.3 via the root package.json packageManager field, so corepack enable gives you the right version.
  • git, and optionally pre-commit (for the git hooks) and Docker (only for image builds).

Clone and install​

git clone https://github.com/hidden-claw/bloom-ai.git
cd bloom-ai
make install        # = pnpm install; one root lockfile for the whole workspace

make help lists every root target (install, lint, typecheck, test, check, run, and the Helm/deploy-script test targets).

Run the API offline​

The backend is apps/server (Node + TypeScript + Express). With the fake LLM provider it needs no API keys and no network:

cd apps/server
BLOOM_LLM_PROVIDER=fake pnpm run dev

make run from the repo root starts the same dev server (export the same environment variables first). The API listens on port 8090 (BLOOM_SERVER_PORT) and serves:

  • GET /healthz - liveness; returns 200 as soon as the process serves HTTP.
  • GET /readyz - readiness; stays 503 until BLOOM_SUPABASE_DB_URL points at a reachable Postgres.

Configuration is environment-only: the server reads process environment variables and never loads a .env file itself (in deployment, the pipeline renders .env into the container environment). Use .env.example at the repo root as the catalog of every BLOOM_* variable, and export the ones you need in your shell. Two to know early:

  • BLOOM_LLM_PROVIDER - anthropic by default; fake produces deterministic placeholder artifacts for offline work.
  • BLOOM_SUPABASE_DB_URL - the Postgres DSN. Without it the server still boots and serves its health surface, but the database-backed API routes (projects, auth, admin, webhooks) are not mounted - wire a real database to exercise the full flow. See Running locally for wiring real Claude/Telegram/GitHub credentials.

Run the dashboard​

The user dashboard is apps/web (React + Vite):

cd apps/web
pnpm dev            # http://localhost:5173

The dev server proxies /api to the deployed API by default (https://bloom-server.exe.xyz), so the browser stays same-origin and you can develop against real sessions. Point it at your local API instead with:

VITE_DEV_API_TARGET=http://localhost:8090 pnpm dev

Completing the Google sign-in against a local API additionally requires the API to be pointed back at the SPA (BLOOM_DASHBOARD_URL=http://localhost:5173) with a matching authorized redirect URI - see the apps/web README.

The admin console (apps/admin) works the same way on port 5174 - see Admin console basics.

Run this docs site​

pnpm --filter @bloom/docs dev    # http://localhost:3000, live reload

The quality gate​

Every package carries the same local merge gate CI enforces - lint, typecheck, tests, build:

make check          # = pnpm run check, fanned out to every workspace package

or per package (faster while iterating), e.g. cd apps/server && pnpm run check. make lint, make typecheck, and make test run the individual stages, and make hooks installs the pre-commit + commit-msg git hooks (Conventional Commits are enforced).

Where next​

  • Core workflows - drive a project through Bloom end to end.
  • Running locally - wiring real credentials into the API.
  • AGENTS.md - the contributing workflow and quality bar, if you plan to change Bloom itself.