Workflow:Helicone Helicone Local Development Setup
| Knowledge Sources | |
|---|---|
| Domains | DevOps, Local_Development, Docker |
| Last Updated | 2026-02-14 06:00 GMT |
Overview
End-to-end process for setting up a complete local Helicone development environment using Docker Compose for infrastructure services and bare-metal processes for application services with hot reload.
Description
This workflow describes how to run the complete Helicone platform locally for development and testing. The setup involves starting infrastructure services (PostgreSQL via Supabase, ClickHouse for analytics, MinIO for object storage, and Redis for caching) using Docker Compose, running database migrations, and starting the application services (Jawn backend, Next.js web frontend, and Cloudflare Worker proxies) with hot reload for rapid development iteration.
The Docker Compose configuration uses a profile-based system that allows starting different subsets of services depending on the development task. The infrastructure can be started independently while application services run bare-metal for faster feedback loops. The system includes seeded test data with pre-configured users, organizations, and API keys.
Usage
Execute this workflow when setting up a new Helicone development environment, when onboarding a new contributor, or when you need to test the full request flow locally from client to LLM provider through the observability pipeline. This is the standard development workflow for all Helicone contributors.
Execution Steps
Step 1: Prerequisites Installation
Install the required system dependencies: Docker and Docker Compose for running infrastructure, Node.js (v20+) via NVM for running application services, Yarn as the package manager, and Wrangler for Cloudflare Worker development. Optionally install the Supabase CLI for database management.
Key considerations:
- Node.js v20 or v22 is required (use NVM for version management)
- Docker must have sufficient memory allocated (recommended 8GB+)
- Wrangler is needed only if developing worker proxy features
Step 2: Environment Configuration
Clone the repository, copy environment example files to create local configurations, and update API keys and service URLs. The key environment files are the root .env and valhalla/jawn/.env. After configuration, start Supabase which provides PostgreSQL and prints the anonymous and service keys needed for the environment files.
Key considerations:
- The root .env configures shared infrastructure settings
- The Jawn .env configures backend-specific settings including database connection strings
- Supabase start command outputs the Anon Key and Service Key that must be added to .env files
- Exclude unnecessary Supabase services (realtime, storage-api, imgproxy) for faster startup
Step 3: Start Infrastructure Services
Start the infrastructure layer using Docker Compose. This brings up PostgreSQL (via Supabase, port 54388), ClickHouse (HTTP port 18123, native port 19000), MinIO (API port 9000, console port 9001), and Redis (port 6379). The helicone-compose.sh helper script manages Docker Compose profiles for different deployment configurations.
Key considerations:
- Use the "infra" profile to start only infrastructure: ./helicone-compose.sh infra up
- MinIO automatically creates required buckets (request-response-storage, prompt-body-storage, hql-store) via the minio-setup service
- Services start in dependency order with health checks ensuring readiness
- ClickHouse migrations must be run after the container is healthy
Step 4: Run Database Migrations
Execute ClickHouse schema migrations using the Python migration tool. This creates the analytics tables, materialized views, and indexes needed for the request logging pipeline. Supabase migrations are typically applied automatically on start, creating the PostgreSQL schema for application data.
Key considerations:
- The ClickHouse migration tool requires Python with tabulate and yarl packages
- Run migrations with: python3 clickhouse/ch_hcone.py --upgrade --skip-confirmation --no-password
- Supabase seeds create test users (test@helicone.ai/password, admin@helicone.ai/password)
- If migrations change, the ClickHouse migration runner Docker image must be rebuilt
Step 5: Start Application Services
Start the three application services in separate terminals. The Jawn backend (Express.js on port 8585) serves the API and processes logs. The Web frontend (Next.js on port 3000) serves the dashboard UI. Optionally start one or more Worker proxies using Wrangler for local proxy development.
Key considerations:
- Jawn: cd valhalla/jawn && yarn && yarn dev (port 8585)
- Web: cd web && yarn && yarn dev:local (port 3000) or yarn dev:better-auth for full auth
- Workers run on different ports by type: OPENAI_PROXY (8787), HELICONE_API (8788), GATEWAY_API (8789), ANTHROPIC_PROXY (8790), AI_GATEWAY_API (8793)
- The dev:local web command uses simpler local authentication
- All services support hot reload for rapid development
Step 6: Verification and Testing
Verify the setup by logging into the dashboard at localhost:3000 with the test credentials, switching to the correct organization, and sending a test LLM request through the local proxy. Confirm the request appears in the dashboard with correct cost calculation and response data.
Key considerations:
- Login with test@helicone.ai / password
- Switch to "Organization for Test" in the org selector to see test requests
- Test requests use the Helicone-Auth header with the seeded API key
- The default "My Organization" shows demo/preview data, not actual requests
- Use curl or the OpenAI SDK pointed at localhost proxy to send test requests