From zero to running in minutes

Local dev environment,
up in minutes.

Describe single or multiple apps in one file. Kustron handles the rest — local k8s cluster, registry, build, deploy.

$ npm install -g kustron

Requires OrbStack or Docker Desktop, k3d, and kubectl. No Kubernetes knowledge required.

How it works

Four commands. Real dev environment.

Kustron manages a local k3d cluster with a built-in container registry. You define what to run. It handles the rest.

Step 01

Initialise

Create a kustron-env.yaml in your project folder, pre-filled with your app name.

$ kustron env init
Step 02

Edit the file

Set ports, add more apps, configure env vars. Or just set the port and move on.

kustron-env.yaml
Step 03

Bring it up

One command spins up the cluster, builds images, and deploys everything.

$ kustron env up
Step 04

Iterate

Add apps, change config, redeploy. The file is the source of truth.

$ kustron env reload
kustron-env.yaml

One file. Your whole environment.

Apps discover each other by name. Exposed apps are available at localhost:<port>.

kustron-env.yaml 
          
          config:
            namespace: kustron-env        # all apps share this namespace

          apps:
            # Build from local source or git repo
            - name: api
              source: ./services/api      # or: git@github.com:org/repo.git
              port: 3000
              exposed: true               # reachable at localhost:3000
              ha: true                    # min 2 replicas, autoscales to 5
              env:
                NODE_ENV: production
                DB_HOST: postgres         # 'postgres' resolves via k8s DNS

            # Run an existing container image
            - name: postgres
              image: postgres:15
              port: 5432
              env:
                POSTGRES_PASSWORD: secret
                POSTGRES_DB: myapp

            # Deploy a Helm chart
            - name: prometheus
              helm:
                chart: kube-prometheus-stack
                repo: https://prometheus-community.github.io/helm-charts
                version: "45.0.0"
                values:
                  grafana.enabled: "true"
App types

Deploy anything.

Every app type shares the same namespace. They reach each other at http://<name>:<port>.

📁

Local source

Point to a folder. Kustron uses your Dockerfile if it exists, or Railpack to containerize automatically.

source: ./path
🔗

Git repository

Provide a git SSH URL. Kustron clones it, builds it, and deploys it. SSH access must already be set up.

source: git@…
📦

Container image

Use any image from Docker Hub or any registry. Perfect for databases and third-party services.

image: postgres:15
⎈

Helm chart

Install any Helm chart into your environment. Pass values directly from the yaml file.

helm: {chart: …}
Commands

Everything you need. Nothing you don't.

env
kustron env init Create a kustron-env.yaml in the current folder, pre-filled with the folder name as the app.
kustron env up Bring up the cluster and deploy all apps from kustron-env.yaml. Idempotent — safe to re-run.
kustron env reload Tear down and rebuild the entire environment. Run this after changing kustron-env.yaml.
kustron env down Tear everything down. The yaml file is untouched.
kustron env show-spec Pretty-print the full kustron-env.yaml schema with annotations.
apps
kustron apps add [flags] Add an app entry to kustron-env.yaml. Then run kustron env reload to apply.
kustron apps remove <name> Remove an app entry from kustron-env.yaml. Then run kustron env reload to apply.
Prerequisites

What you need installed.

Kustron checks for these on install and tells you exactly what to do if anything is missing.

⚡

Recommended: OrbStack over Docker Desktop. OrbStack starts in ~2 seconds (vs 30+), uses a fraction of the memory, and has native Apple Silicon support. orbstack.dev →

required

Docker runtime

OrbStack (recommended) or Docker Desktop

required

k3d

brew install k3d  ·  k3d.io/installation

required

kubectl

brew install kubectl

optional

Railpack

Only needed when deploying source without a Dockerfile. railpack.io

optional

Helm

Only needed when deploying Helm chart apps. brew install helm

optional

git

Only needed when deploying from a git SSH URL. Usually pre-installed.

Beyond localhost

One VM. A real live environment.

Kustron isn't just for local development. Spin it up on any cloud VM and expose your whole stack — APIs, frontends, databases — to the real internet. No cluster management. No cloud-native complexity.

1

Get a VM

Any Linux instance works — EC2, DigitalOcean Droplet, Hetzner Cloud, Linode. Even a $6/month box is enough for a real multi-service stack.

2

Install prereqs & add your SSH key

Install Docker, k3d, kubectl, and kustron. Add your GitHub (or GitLab) SSH key so kustron can pull private repos directly on the instance.

3

Write your kustron-env.yaml

List your apps with exposed: true for anything that needs to be public. Kustron maps each port to the VM's network interface.

4

Bring it up

One command. Cluster, registry, images, deployments — all at once.

5

Open the firewall & share the URL

Allow the exposed ports in your security group (AWS) or firewall rules. That's it — your stack is live at <vm-ip>:<port>.

Your VM — 1.2.3.4
kustron environment
frontend :8080 live
api :3000 live
postgres :5432
redis :6379
↓
1.2.3.4:8080  ·  1.2.3.4:3000
accessible from anywhere
🔒 Only open ports you intend to expose. Internal services like postgres and redis stay internal — never set exposed: true on them.