Quick Start

Go from zero to production-like Kubernetes in under 5 minutes.

No DNS configuration. No certificate headaches. No port-forwarding gymnastics. Just a complete, working Kubernetes environment ready for development.

---

What You’ll Build

By the end of this guide, you’ll have:

• ✅ Multi-node Kubernetes cluster running locally
• ✅ PostgreSQL database accessible at postgres.dev.me
• ✅ pgAdmin web UI at https://postgres-ui.dev.me (no certificate warnings!)
• ✅ Local container registry at cr.dev.me
• ✅ Your own app deployed and accessible via HTTPS

Total time: ~5 minutes (mostly waiting for downloads)

%% title: LoKO Setup Flow %%
graph TD
    Start["🚀 Start Here<br/>$ loko config generate"]
    Config["📝 Config Created<br/>loko.yaml with defaults"]
    Edit["✏️ Edit as Needed<br/>Add workloads, customize"]
    Command["⚡ One Command<br/>$ loko create"]

    subgraph Magic["✨ LoKO Sets Up Everything"]
        direction LR
        K8s["☸️ Kubernetes Cluster<br/>Multi-node Kind cluster"]
        DNS["🌐 DNS Resolution<br/>*.dev.me auto-resolves"]
        Certs["🔒 TLS Certificates<br/>Wildcard HTTPS certs"]
        Reg["📦 Container Registry<br/>Local OCI registry (Control Plane)"]
        Tunnel["🔌 TCP Tunnel<br/>Dynamic port routing via IngressRouteTCP"]
        Ports["🚪 Intelligent Routing<br/>HTTP/HTTPS auto-routed"]
    end

    Result["🎉 Everything Just Works!"]

    subgraph Examples["💡 What You Can Do"]
        direction LR
        Ex1["🗄️ Access Services<br/>psql -h postgres.dev.me<br/>redis.dev.me:6379"]
        Ex2["🌐 Deploy Web Apps<br/>https://myapp.dev.me"]
        Ex3["💻 Develop Your App<br/>Use databases, caches,<br/>messaging, etc."]
        Ex4["📦 Push Images/Charts<br/>docker push cr.dev.me/myapp<br/>helm push chart.tgz oci://cr.dev.me"]
    end

    Start -->|Generates| Config
    Config -->|Optional| Edit
    Edit -->|Run| Command
    Command -->|Automatic| K8s
    Command -->|Automatic| DNS
    Command -->|Automatic| Certs
    Command -->|Automatic| Reg
    Command -->|Automatic| Tunnel
    Command -->|Automatic| Ports

    K8s -.-> Result
    DNS -.-> Result
    Certs -.-> Result
    Reg -.-> Result
    Tunnel -.-> Result
    Ports -.-> Result

    Result --> Ex1
    Result --> Ex2
    Result --> Ex3
    Result --> Ex4

    classDef startStyle fill:#1e88e5,stroke:#1565c0,stroke-width:3px,color:#fff,font-weight:bold
    classDef configStyle fill:#8e24aa,stroke:#6a1b9a,stroke-width:3px,color:#fff,font-weight:bold
    classDef editStyle fill:#fb8c00,stroke:#e65100,stroke-width:3px,color:#fff
    classDef commandStyle fill:#e53935,stroke:#c62828,stroke-width:4px,color:#fff,font-weight:bold
    classDef magicStyle fill:#00897b,stroke:#00695c,stroke-width:2px,color:#fff
    classDef resultStyle fill:#43a047,stroke:#2e7d32,stroke-width:4px,color:#fff,font-weight:bold
    classDef exampleStyle fill:#546e7a,stroke:#37474f,stroke-width:2px,color:#fff

    class Start startStyle
    class Config configStyle
    class Edit editStyle
    class Command commandStyle
    class K8s,DNS,Certs,Reg,Tunnel,Ports magicStyle
    class Result resultStyle
    class Ex1,Ex2,Ex3,Ex4 exampleStyle

---

Prerequisites

Verify you have everything installed:

loko check prerequisites

Missing something? → Installation Guide

First-run prerequisite checks

When you run any loko command for the first time, loko automatically checks if required tools (Docker, git, kind, kubectl, helm, cfssl, helmfile) are installed. If any are missing, you’ll see clear installation guidance. Use loko check prerequisites to manually check at any time.

---

Step 1: Generate Your Configuration

LoKO creates a smart default configuration for you:

loko config generate

What this does:

• Auto-detects your local IP by default
• Creates loko.yaml with sensible defaults
• Sets up domain: dev.me (works out of the box)

Want to regenerate config?

loko config generate --force

Overwrites existing loko.yaml with fresh defaults.

Need to override IP detection?

loko config generate --local-ip 192.168.0.10

Use this if auto-detection picks the wrong address or cannot detect one in your environment.

---

Step 2: Add PostgreSQL

Let’s add a database before creating the cluster:

loko workloads add postgres

This updates loko.yaml to include PostgreSQL with pgAdmin.

Edit if needed: Open loko.yaml and customize settings like storage size, passwords, or worker node count.

---

Step 3: Create Everything

One command creates the entire environment:

loko env create

What happens automatically:

1. 🌐 DNS resolution - dnsmasq configured for *.dev.me
2. 🔒 TLS certificates - Wildcard cert generated and trusted
3. ☸️ Kubernetes cluster - Multi-node Kind cluster created
4. 📦 Container registry - Local OCI registry deployed
5. 🔌 Intelligent routing - Traefik ingress + TCP routing configured
6. 🗄️ PostgreSQL deployed - Database + pgAdmin running

First time? This takes ~3-5 minutes (downloading images). Subsequent runs are much faster.

---

Step 4: Verify Everything Works

Check cluster status:

loko status

Expected output:

╭─────────────────────────── Cluster Status ────────────────────────────╮
│ Cluster: dev-mac                                                      │
│ Provider: kind                                                        │
│ Status: ✓ Running                                                     │
╰───────────────────────────────────────────────────────────────────────╯

╭─────────────────────────── Node Status ───────────────────────────────╮
│ NAME                     ROLE           STATUS   AGE                  │
│ dev-mac-control-plane    control-plane  Ready    3m                   │
│ dev-mac-worker           worker         Ready    3m                   │
╰───────────────────────────────────────────────────────────────────────╯

List your workloads:

loko workloads list

Expected output:

╭─────────────────────────── Workloads ─────────────────────────────╮
│ NAME      STATUS    DNS                      PORTS                │
│ postgres  Running   postgres.dev.me          5432                 │
│ pgadmin   Running   postgres-ui.dev.me           443                  │
╰───────────────────────────────────────────────────────────────────╯

---

Step 5: Access PostgreSQL

Option 1: Direct Connection (Recommended)

psql -h postgres.dev.me -U postgres

That’s it. DNS resolves, port routing works, you’re connected.

Option 2: Web UI

Open your browser:

https://postgres-ui.dev.me

No certificate warnings - LoKO already generated the CA and attempted to install trust.

Get credentials:

loko secrets show

Output:

{
  "postgres": {
    "password": "auto-generated-secure-password"
  },
  "pgadmin": {
    "email": "admin@dev.me",
    "password": "another-auto-generated-password"
  }
}

---

Step 6: Deploy Your Own App

Let’s deploy a simple web app that uses PostgreSQL.

Build and Push to Local Registry

# Build your app
docker build -t cr.dev.me/myapp:latest .

# Push to local registry (no Docker Hub needed!)
docker push cr.dev.me/myapp:latest

Deploy to Kubernetes

Create deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 2
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: cr.dev.me/myapp:latest
        env:
        - name: DATABASE_URL
          value: "postgres://postgres:PASSWORD@postgres.dev.me:5432/mydb"
---
apiVersion: v1
kind: Service
metadata:
  name: myapp
spec:
  selector:
    app: myapp
  ports:
  - port: 8080
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp
spec:
  rules:
  - host: myapp.dev.me
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: myapp
            port:
              number: 8080

Deploy it:

kubectl apply -f deployment.yaml

Access your app:

https://myapp.dev.me

✅ HTTPS works ✅ DNS resolves ✅ App connects to PostgreSQL ✅ Exactly like production

---

Real Developer Workflow Example

Here’s a typical development session:

# Morning: Start your cluster
loko env create

# Add a cache
loko workloads add redis
loko workloads deploy redis

# Build and test your app
docker build -t cr.dev.me/api:v2 .
docker push cr.dev.me/api:v2
kubectl set image deployment/myapp myapp=cr.dev.me/api:v2

# Check logs
kubectl logs -f deployment/myapp

# Connect to database for debugging
psql -h postgres.dev.me -U postgres

# Evening: Stop cluster (keeps all data)
loko env stop

---

Managing Your Environment

Stop (Preserves Data)

loko env stop

Stops all containers but keeps persistent volumes.

Start (After Stopping)

loko env start

Restarts your cluster with all data intact.

Destroy (Removes Cluster)

loko env destroy

Deletes cluster but keeps loko.yaml and generated configs.

Clean (Complete Reset)

loko env clean

Removes everything: cluster, DNS, certificates, generated files.

---

Add More Workloads

LoKO has pre-configured workloads. Add what you need:

# Databases
loko workloads add mysql
loko workloads add mongodb

# Cache (Redis-compatible)
loko workloads add valkey

# Messaging
loko workloads add rabbitmq
loko workloads add nats
loko workloads add redpanda

# Storage (S3-compatible)
loko workloads add garage

# DevOps/GitOps
loko workloads add forgejo
loko workloads add argocd
loko workloads add flux-operator

# Collaboration
loko workloads add excalidraw

# DevTools
loko workloads add mock-smtp-sms

# Deploy all enabled workloads
loko workloads deploy --all

Each workload includes:

• ✅ DNS configuration
• ✅ Auto-generated passwords
• ✅ Health checks
• ✅ Web UI tools (where applicable)
• ✅ TCP port routing

See all available workloads: Workload Catalog

---

Common Commands

What You Want	Command
Check if cluster is running	loko status
List all workloads	loko workloads list
Deploy a workload	loko workloads deploy <name>
View workload logs	loko logs workload <name>
Get connection info	loko secrets show
Validate configuration	loko config validate
Stop cluster	loko env stop
Start cluster	loko env start
Destroy cluster	loko env destroy

---

Troubleshooting

”postgres.dev.me” Doesn’t Resolve

Check DNS:

loko check dns

macOS: DNS should auto-configure via /etc/resolver/ Linux: LoKO supports systemd-resolved and NetworkManager-based setups

Fix:

loko dns recreate

---

“Cannot connect to Docker daemon”

macOS:

open -a Docker
# Wait for Docker Desktop to start

Linux:

sudo systemctl start docker

---

“Port already in use”

LoKO uses ports 80 and 443 (Traefik). DNS runs in-cluster via an auto-selected DNS port — no host port required.

Check what’s using HTTP/HTTPS ports:

lsof -i :80
lsof -i :443

Kill conflicting processes (e.g. Apache, Nginx) before running loko env create.

---

Still Stuck?

See Troubleshooting Guide or open an issue.

---

What Makes This Different?

Coming from other tools? Here’s why LoKO feels magical:

vs Docker Compose

• ✅ Real Kubernetes - Test Helm charts, Ingress, NetworkPolicies
• ✅ Multi-node clusters - Test pod scheduling and affinity
• ✅ Production parity - Behaves like real K8s

vs Minikube

• ✅ Faster - No VM overhead (on Linux/Docker Desktop)
• ✅ Multi-node - Minikube is single-node only
• ✅ Better networking - Direct container access

vs Bare Kind

• ✅ DNS auto-configured - No /etc/hosts hacking
• ✅ TLS included - No certificate warnings
• ✅ Container registry - No Docker Hub needed
• ✅ Workload catalog - Pre-configured services
• ✅ TCP routing - Direct database access from host

LoKO uses Kind under the hood, but adds all the batteries you need.

---

Next Steps

Explore Workloads

Add databases, caches, messaging, storage, and more

Learn more →

Customize Configuration

Multi-node clusters, custom domains, advanced networking

Learn more →

Use the Registry

Push images, Helm charts, and OCI artifacts

Learn more →

See Comparisons

Deep dive into LoKO vs alternatives

Learn more →

---

Ready to dive deeper? Understand the architecture →