Local services on k3d

Run the services your app needs. Keep the setup in one file.

Choose the services in pyahu.yaml. Pyahu creates the local cluster, waits for it to become ready, and prints the endpoints your app can use.

Start with PostgreSQL See configuration
project/

A working database in three commands

  1. 01

    Create the project file

    The default preset contains PostgreSQL only.

    $ pyahu init
  2. 02

    Start the stack

    Pyahu creates k3d and waits for PostgreSQL.

    $ pyahu up
  3. 03

    Load the connection

    Use the generated values in your current shell.

    $ eval "$(pyahu env)"

Requires Docker or Podman and k3d 5.x.

When it helps

A local stack the whole team can repeat

Pyahu is useful when application dependencies have outgrown a few ad-hoc container commands, or when local behavior needs to stay close to Kubernetes.

One project file

Services, ports and local defaults live in pyahu.yaml, next to the code that uses them.

Kubernetes behavior

Ingresses, Secrets, ConfigMaps and persistent volumes are real resources in a local k3d cluster.

The full dependency chain

Run database, identity, messaging and CDC together when the application needs all of them.

Included services

Start small. Add only what the app uses.

The minimal preset runs PostgreSQL. The platform preset enables the full stack, and every service can be turned on or off in the same file.

PostgreSQL

Databases and optional read replicas

localhost:5432

ZITADEL

Local identity and OIDC

https://zitadel.localhost

RabbitMQ

AMQP and management UI

localhost:5672

Redis

Valkey-compatible data and streams

localhost:6379

Kafka

Single-broker KRaft for local events

localhost:9092

Kafka Connect

Connectors, plugins and Debezium CDC

localhost:8083

Kafka UI

Topics, consumers and connectors

https://kafka-ui.localhost

The full platform preset runs seven real services. Plan for 4 CPU cores, 8 GiB of container memory and 15 GiB of free disk. Use the minimal preset on smaller machines.

No hidden cluster

Use simple commands. Inspect Kubernetes when you need it.

The normal workflow does not require kubectl or Helm. The cluster is still yours: export its kubeconfig and inspect every workload, volume and event when a service needs debugging.

Read the command guide 
$ pyahu services

SERVICE   STATUS  VERSION     ENDPOINTS
postgres  ready   18.4        localhost:5432
redis     ready   8.1-alpine  localhost:6379
kafka     ready   4.3.0       localhost:9092

$ export KUBECONFIG="$(pyahu kubeconfig)"
$ kubectl get pods -n pyahu-local-dev
postgres-0     1/1 Running
redis-0        1/1 Running

Local by default

Clear behavior around ports, secrets and data

Bound to this machine

Host ports bind to 127.0.0.1 instead of being published to the local network.

Secrets stay out of summaries

pyahu up masks passwords and credentials. pyahu env is the explicit command for real values.

Data is not removed by surprise

pyahu down retains local storage. Permanent removal requires --purge-data and confirmation.

Kafka Connect

Keep local CDC beside the rest of the stack

Declare a Debezium PostgreSQL connector in pyahu.yaml. Pyahu applies it, checks every task, and removes registrations that no longer belong to the file. Custom connector plugins can be downloaded with a required SHA-256 or read from a local jar.

Kafka Connect and Debezium guide 
services:
  kafkaConnect:
    connectors:
      - name: app-cdc
        kind: debezium.postgres
        database: app
        tables:
          include:
            - public.orders

Install

Install the binary, then run doctor

Releases are available for macOS, Linux and Windows. The install script and built-in upgrade verify the published checksum.

# macOS and Linux
$ curl -fsSL https://cli.pyahu.io/install.sh | sh
$ pyahu doctor
All install methods, prerequisites and shell completionView releases on GitHub

Get started

Start with PostgreSQL. Add the rest when your app needs it.

Installation guideOpen the docs