Local development

🛠️ Local development

Use Node.js 22 or later. The repository has separate API and web lockfiles:

npm ci
npm --prefix web ci

Application storage defaults to /data, which is normally writable only in the container. Point all persistent paths at the ignored checkout-local data/ directory before running the API directly:

mkdir -p data
export STORE_PATH="$PWD/data/accounts.json"
export OAUTH_STATE_PATH="$PWD/data/oauth-state.json"
export TRACE_FILE_PATH="$PWD/data/requests-trace.jsonl"
export TRACE_STATS_HISTORY_PATH="$PWD/data/requests-stats-history.jsonl"
export CODEX_PROJECTS_PATH="$PWD/data/codex-projects.json"
export JOBS_DB_PATH="$PWD/data/jobs.sqlite"

Set non-placeholder ADMIN_TOKEN and PROXY_API_KEY values as well if the development server is reachable beyond your machine. Build the dashboard once before starting the watched API server:

npm run build:web
npm run dev

Production-style validation:

npm run build
npm test
npm start

To exercise the native edge locally, build the Rust workspace and start the control-plane pair with the same loopback split used by Compose:

cargo test -p multivibe-v1-edge
# Terminal 1: Node control plane
MULTIVIBE_CONTROL_PLANE=true \
  V1_EDGE_INTERNAL_JOB_TOKEN="local-development-only" \
  PORT=1456 HOST=127.0.0.1 npm run dev

# Terminal 2: native Rust edge
V1_EDGE_PORT=1455 V1_EDGE_HOST=0.0.0.0 \
  NODE_CONTROL_PLANE_URL=http://127.0.0.1:1456 \
  V1_EDGE_INTERNAL_JOB_TOKEN="local-development-only" \
  cargo run -p multivibe-v1-edge

Available scripts:

Command	Purpose
npm run dev	Watch the TypeScript API server
npm run build:web	Type-check and build the React dashboard
npm run build:api	Compile the API
npm run build:proxy-core-native	Build the optional Rust/N-API payload inspector
npm run build	Build dashboard and API
npm test	Run the Node test suite
npm run test:proxy-core-native	Build and test the Rust/N-API addon against shared fixtures
npm start	Run the compiled server with instrumentation