Run local application services on k3d from one project file.
Website · Documentation · Releases
Pyahu creates a local k3d cluster and runs the services your application needs.
The setup lives in pyahu.yaml, so a team can keep the same ports, service
versions and defaults next to its code.
The normal workflow uses a few CLI commands. When something needs debugging,
the generated Kubernetes resources remain available through kubectl.
You need Docker or Podman running and k3d 5.x installed.
curl -fsSL https://cli.pyahu.io/install.sh | sh
mkdir my-app && cd my-app
pyahu init # writes pyahu.yaml with PostgreSQL enabled
pyahu doctor # checks the container runtime, k3d and local ports
pyahu up
eval "$(pyahu env)"Your application can now use the generated POSTGRES_URL. To see the service
state and endpoint:
$ pyahu services
cluster: pyahu-local
namespace: pyahu-local-dev
state: running
SERVICE STATUS VERSION ENDPOINTS
postgres ready 18.4 localhost:5432- One project file. Services, ports and local defaults are reviewable in
pyahu.yaml. - A repeatable stack.
pyahu upcreates or reconciles the same resources for every developer. - Real Kubernetes behavior. Ingresses, Secrets, ConfigMaps and persistent volumes run in k3d and can be inspected when needed.
- More than a database. Database, identity, messaging and CDC can run together without a separate setup for each service.
If all you need is a disposable database and Kubernetes behavior does not matter, a single container may be simpler. Pyahu is most useful when a project has several dependencies or benefits from a local Kubernetes environment.
| Preset | What it starts | Good for |
|---|---|---|
minimal |
PostgreSQL | Small projects and constrained machines |
platform |
All supported services | Applications that need the full dependency chain |
pyahu init --preset minimal # default
pyahu init --preset platformThe full preset runs seven services. Allocate at least 4 CPU cores and 8 GiB of
memory to the container runtime, with 15 GiB of free disk. Start with minimal
if you are unsure.
| Service | Use | Local endpoint |
|---|---|---|
| PostgreSQL | Databases and optional read replicas | localhost:5432 |
| ZITADEL | Identity and OIDC | https://zitadel.localhost |
| RabbitMQ | AMQP and management UI | localhost:5672 · https://rabbitmq.localhost |
| Redis | Valkey-compatible data and streams | localhost:6379 |
| Kafka | Local event streaming with KRaft | localhost:9092 |
| Kafka Connect | Connectors, plugins and Debezium CDC | http://localhost:8083 |
| Kafka UI | Topics, consumers and connectors | https://kafka-ui.localhost |
Services are enabled independently. A small stack can stay small:
apiVersion: cli.pyahu.io/v1alpha1
kind: Stack
metadata:
name: local-dev
services:
postgres:
enabled: true
databases:
- name: app
redis:
enabled: trueSee Configuration for all supported fields and the changes that require recreating the cluster.
pyahu services # services, state and endpoints
pyahu describe postgres # configuration and pod details, with secrets masked
pyahu logs postgres --follow # service logs
eval "$(pyahu env)" # connection variables for the current shell
export KUBECONFIG="$(pyahu kubeconfig)"
kubectl get pods -n pyahu-local-dev
pyahu down # remove the cluster and retain local data
pyahu down --purge-data --yes # permanently remove retained data tooHost ports bind to 127.0.0.1. Command summaries mask passwords and tokens;
pyahu env is the explicit way to print real connection values. Local data is
retained under ~/.pyahu/clusters/<cluster>/storage unless --purge-data is
used.
Connectors can live in the same project file as the rest of the stack:
services:
kafkaConnect:
enabled: true
connectors:
- name: app-cdc
kind: debezium.postgres
database: app
tables:
include: [public.orders]Pyahu applies the connector and checks each task, not only the top-level connector state. It removes registrations that were previously managed by this stack and are no longer declared, while leaving manually created connectors alone. Custom plugin downloads require a SHA-256 value.
Read Kafka Connect and Debezium for optional connectors, custom plugins and sink configuration.
- mise to pin the CLI version in a project
- the install script for macOS and Linux
go install github.com/pyahu/cli/cmd/pyahu@latestwith Go 1.26+- archives for macOS, Linux and Windows from GitHub Releases
The install script and pyahu upgrade verify the checksum published with the
release. Full instructions are in the installation guide.
If your team runs on Pyahu Cloud, this CLI can also
point kubectl at one of your environments. Sign in once, add the context once,
and use plain kubectl from then on:
pyahu login # approve the code in your browser
pyahu kube list # environments you can reach
pyahu kube config # add the context to your kubeconfig
kubectl get pods # from here on it is just kubectlThree things worth knowing:
- The kubeconfig entry holds no credential. It records where the cluster is
and that this CLI should be asked for a token when one is needed.
kubectlcallspyahuon its own to refresh it, so nothing long-lived sits on disk. - Your kubeconfig is backed up before it is changed, and every other context in it is left alone.
- What you can do there is decided by your role, on the server, every time a token is issued. Losing access takes effect within minutes.
pyahu kube doctor says which step is missing when kubectl does not work.
Pyahu focuses on local infrastructure, plus the one remote thing above: pointing
kubectl at a Pyahu Cloud environment you already have access to. It does not
deploy applications, provision remote clusters or replace production
infrastructure tooling.
Contributions are welcome. See CONTRIBUTING.md for the local setup and development commands. Please follow the Code of Conduct and report vulnerabilities through the security policy.
MIT © Pyahu