VENI-AIDOCS
03 / Develop · Veni builder · Run

Run Veni builder ​

Clone, configure, run. bun is the direct path; make wraps it.

Prerequisites ​

  • Docker (Compose v2), Bun, and Node 20.12+ — the platform toolchain (full list).
  • The veni CLI on PATH — the Scaffold feature shells out to it.
  • The full platform running locally (Shell + Docker infra) — see Get started.

1 · Clone ​

bash
git clone https://github.com/VENIZIA-AI/veni-builder.git && cd veni-builder

2 · Configure ​

bash
cp api/.env.example api/.env
cp ui/.env.example ui/.env

api/.env — only the signing secret is required; the rest already work locally. APP_ENV_NODE_ENV=development and APP_ENV_BUILDER_ENABLED=true are what unlock the scaffold + CLI-distribution endpoints:

bash
APP_ENV_PORT=3010
APP_ENV_JWT_SECRET=                                                     # REQUIRED · openssl rand -hex 32
APP_ENV_NODE_ENV=development                                            # must be development for scaffolding
APP_ENV_BUILDER_ENABLED=true                                           # gate for scaffold + CLI endpoints
# APP_ENV_SCAFFOLD_ROOT=...                                            # monorepo root the CLI runs from (default: 3 levels up)
APP_ENV_SHELL_JWKS_URL=http://localhost:3000/api/.well-known/jwks.json  # verify Shell tokens
# APP_ENV_SHELL_PUBLIC_API_URL=...                                     # Shell API as a LAPTOP reaches it — baked
                                                                       # into install.sh for the device flow.
                                                                       # Locally it falls back to the gRPC URL;
                                                                       # in K8s you must set it (see below).

Deploying the Builder? Set APP_ENV_SHELL_PUBLIC_API_URL

The installer it serves runs the device flow against a baked-in Shell URL, from a developer's machine. Unset, it falls back to APP_ENV_SHELL_GRPC_URL — correct locally, cluster-internal in Kubernetes (http://shell-api:3000/api), which no laptop can resolve. The symptom is an installer that stops at "could not start sign-in".

ui/.env — just the API URL and port:

bash
VITE_API_URL=http://localhost:3010/api   # must include /api
VITE_PORT=3011

3 · Run ​

Install dependencies, then run the API and UI in two terminals:

bash
# API — terminal 1 (:3010)
cd api && bun install && bun run dev

# UI — terminal 2 (:3011)
cd ui && bun install && bun run dev
bash
make install
make dev-api    # :3010
make dev-ui     # :3011

Open http://localhost:3011 — / and /docs are the component catalog. Shortcut: make dev runs both in the background (make stop to stop, make help lists every target).

Next: install the veni CLI, then scaffold an app.

Common snags ​

SymptomFix
"Can't reach the Builder API"Check the API is up on :3010 and VITE_API_URL ends with /api.
API crash-loops: Environment validation failed: APP_ENV_JWT_SECRETBlank in .env.example; set APP_ENV_JWT_SECRET=$(openssl rand -hex 32) in api/.env.
Scaffold form shows "Development only" / button disabledThe API gates scaffolding on APP_ENV_NODE_ENV=development and APP_ENV_BUILDER_ENABLED=true. Set both and restart the API.

See also ​