Local Development

The local development workflow follows a strict sequence: configure environment, start infrastructure, start Temporal runtime, run migrations, then start applications.

Prerequisites

Requirement	Details
Node.js	>= 22
pnpm	10.x (`corepack enable && corepack prepare pnpm@10.28.0 --activate`)
Docker	Must be running (for infrastructure services)
1Password CLI	`op` binary, optional for local dev. Only needed if using secrets from 1Password vaults

Step-by-step setup

1. Install dependencies

pnpm install

2. Configure environment

pnpm env:configure

This script copies .env.example to .env (if it does not exist) and upserts all required keys with local development defaults:

Key	Default value
`NODE_ENV`	`development`
`API_PORT`	`4000`
`DATABASE_URL`	`postgres://postgres:postgres@localhost:5432/tx_agent_kit`
`AUTH_SECRET`	`local-dev-auth-secret-123456`
`API_CORS_ORIGIN`	`http://localhost:3000`
`API_BASE_URL`	`http://localhost:4000`
`TEMPORAL_RUNTIME_MODE`	`cli`
`TEMPORAL_ADDRESS`	`localhost:7233`
`TEMPORAL_TASK_QUEUE`	`tx-agent-kit`
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4318`

The script is idempotent. Running it again updates existing keys without duplicating them.

3. Start infrastructure

pnpm infra:ensure

This starts all Docker Compose services under the infra profile and waits for health checks to pass. Services include PostgreSQL, Redis, the OTEL collector, Jaeger, Prometheus, Grafana, and Loki.

If infrastructure is already running, the command exits immediately. See Docker Stack for service details.

4. Start local Temporal CLI runtime

pnpm temporal:dev:up

Use pnpm temporal:dev:status to verify readiness.

5. Run database migrations

pnpm db:migrate

Drizzle ORM migrations run against the database specified in DATABASE_URL. Migrations are defined in packages/db/src/migrations/.

6. Start all applications

pnpm dev

This runs all application dev servers in parallel via Turborepo:

App	URL	Port
Web	`http://localhost:3000`	3000
API	`http://localhost:4000`	4000
Worker	(background process)	n/a
Mobile	Expo DevTools	8081

You can also start individual applications:

pnpm dev:web      # Next.js only
pnpm dev:api      # Effect HTTP API only
pnpm dev:worker   # Temporal worker only
pnpm dev:mobile   # Expo React Native only

Verifying the setup

After starting all services, verify everything works:

# Check API health
curl http://localhost:4000/health

# Open web app
open http://localhost:3000

# Check Temporal CLI runtime
pnpm temporal:dev:status

# Open Grafana dashboards
open http://localhost:3001

Rebuilding contracts

When you change the API, regenerate the OpenAPI spec and client hooks:

# Generate OpenAPI spec from API routes
pnpm openapi:generate

# Regenerate web + mobile API client hooks
pnpm api:client:generate

Running quality checks

# Quick checks (reduced output for agent workflows)
pnpm lint:quiet
pnpm type-check:quiet
pnpm test:quiet

# Full output (for debugging failures)
pnpm lint
pnpm type-check
pnpm test

# Integration tests (resets test DB, requires running infra)
pnpm test:integration

In local development, Docker runs only infrastructure services. Applications run as native Node.js processes for fast hot-reload. In staging and production, applications are deployed as container images built by pnpm deploy:build-images.