Quickstart

Get up and running with Unkey development quickly. Choose your development path based on what you're working on.

Getting Started

Universal Prerequisites

You'll need these tools regardless of your development path:

• Node.js
• pnpm
• Docker
• Bazel (build system)

Initial Setup

Clone the repository and install dependencies:

git clone https://github.com/unkeyed/unkey
cd unkey
make install

This sets up the Go workspace and installs all web dependencies.

Choose Your Development Path

Select the path that matches what you're working on:

Path A: Frontend Development (Dashboard)

Perfect for: Working on the dashboard UI, components, and frontend features.

Setup: Quick and simple - all backend services run automatically in the background.

make local-dashboard

What you get:

• Dashboard running at http://localhost:3000
• All backend services running in Docker containers
• Hot reload for frontend code changes
• Simple, minimal setup focused on UI development

Path B: Backend Development (Go Services)

Perfect for: Working on API services, backend logic, database schemas, and infrastructure.

Setup: Full Kubernetes environment with hot reload for Go services.

Additional Prerequisites

In addition to the universal tools, you'll need:

• Go (for Go development)
• Minikube (local Kubernetes cluster)
• Tilt (development orchestrator)
• ctlptl (cluster management)
• mkcert (local TLS certificates)
• Homebrew (recommended for easy tool installation)

Installation Options

Option 1: Automated Installation (Recommended)

make install-brew-tools

This uses Homebrew to install Minikube, Tilt, and ctlptl automatically.

Option 2: Manual Installation Install tools individually using your preferred method if you're not using Homebrew.

System Requirements

The Kubernetes setup requires more resources:

• RAM: At least 8GB recommended
• CPU: 4+ cores recommended
• Storage: 20GB+ free space
• Docker Desktop or similar container runtime

Depot Configuration (Build Service)

Unkey uses Depot as part of the deployment pipeline during development.

Current Setup (Required for now):

cp ./dev/.env.depot.example ./.env.depot
# Edit ./.env.depot with your Depot credentials

Note: We're working on making Depot optional soon.

Start Backend Development

make dev

What you get:

• Tilt UI at http://localhost:10350 (unified development interface)
• Services accessible on localhost ports:
  • API: http://localhost:7070
  • Ctrl: http://localhost:7091
  • Krane: http://localhost:8070
  • Dashboard: http://localhost:3000
• Hot reload for Go services (automatic rebuild on code changes)
• Production-like Kubernetes environment

Local HTTPS with Frontline (Optional)

To test the full request flow with TLS termination via Frontline, you can enable local HTTPS for *.unkey.local domains.

Prerequisites:

• mkcert - for generating trusted local certificates
• DNS configured to resolve *.unkey.local to 127.0.0.1 (via setup-wildcard-dns.sh)

Setup:

./dev/setup-wildcard-dns.sh

make tunnel

open https://app.unkey.local

How it works:

• Tilt automatically generates trusted TLS certificates using mkcert on first run
• Frontline terminates TLS on port 443 and routes requests based on hostname
• The minikube tunnel binds the LoadBalancer service to your host's ports 80/443

Stop Development Environment

When you're done developing:

make down

This cleanly shuts down the Minikube cluster and cleans up resources.

Environment Configuration

Local Authentication

Unkey has a built-in local auth mode with a permanently logged in user belonging to a single organization. This is perfect for development and testing.

Set this environment variable in your .env file:

AUTH_PROVIDER="local"

Optional Services

WorkOS Authentication (for multi-workspace scenarios):

• AUTH_PROVIDER="workos"
• WORKOS_CLIENT_ID=<your client ID>
• WORKOS_API_KEY=<your API key>
• WORKOS_COOKIE_PASSWORD=<your base64 generated password>

Stripe Billing (for multi-user workspaces):

• STRIPE_SECRET_KEY=<your Stripe secret key>

Common Development Tasks

Running the Unkey CLI

Use make unkey to run any CLI command with your local .env file loaded:

# General syntax
make unkey <command> [subcommands...]
 
# Run services
make unkey run api                    # API server
make unkey run ctrl                   # Control plane service
make unkey run krane                  # K8s management service
make unkey run frontline              # Multi-tenant frontline server
make unkey run sentinel               # Deployment proxy
make unkey run preflight              # Pod mutation webhook
 
# Seed data
make unkey dev seed local             # Seed local development data
make unkey dev seed verifications     # Seed verification events

For commands that need flags with --, use the ARGS variable:

make unkey run api ARGS="--http-port=7071"

Seeding Local Data

Before running services locally, seed your database with test data:

# Start the database
make up
 
# Seed workspace, API, and root key for local development
make unkey dev seed local

This creates everything you need to start making API requests locally.

Testing

# Run unit tests
make test
 
# Run integration tests
make test-integration

Code Quality

# Format code and run linters
make fmt
 
# Build all artifacts
make build