You own a cluster, or you are about to stand one up, and you want your app running on it today. Not next week, after you have learned Kubernetes. Today. This guide takes you from an empty cluster to a live app you can hit in a browser, using nothing but a handful of plain commands. No YAML to write, no dashboards to learn, no platform to hand your code to.

Here is the whole arc before we start: install Burrow into your cluster, wire up your agent, build and push your app image, deploy it by reference, confirm it is healthy, and publish it at a domain with a certificate. Six steps, each one command or close to it.

What you need first

You need a Kubernetes cluster you can reach with kubectl. That can be a managed cluster on DigitalOcean, Hetzner, or Linode, or a single machine you turn into a cluster with Burrow's bootstrap (more on that at the end). You also need a place to put container images that your cluster can pull from, which usually means a registry like GitHub Container Registry or your cloud's registry.

If you have those two things, you are ready. Everything else Burrow installs for you.

Step 1: install Burrow into your cluster

Install the tools, then install Burrow itself into the cluster:

brew install burrow-cloud/tap/burrow
burrow install <context>

The <context> is the name of the cluster in your kubeconfig. If you are not sure what it is called, run burrow install on its own and it lists the contexts it can see, so you can copy the right one.

This step deploys the part of Burrow that holds your cluster credentials and does the real work, along with a small database it uses to track your releases. It waits until everything is ready and then tells you so:

Waiting for Burrow to become ready...
  database ... ✓
  control plane ... ✓

Burrow is installed and ready.

That machinery lives on your cluster, on the nodes you already pay for. It is not a service we run for you, and it does not phone anything home. It is yours.

Step 2: wire up your agent

If you operate through an AI coding agent, point it at Burrow now:

burrow agent claude install

This does two small but important things. It gives your agent permission to run burrow-agent, the scoped command surface built for it, and it denies the agent the full admin CLI. So the agent can deploy, read logs, scale, and roll back, but it cannot reach past the guardrails you set. It also drops a short orientation note where the agent will read it, so it knows how to drive Burrow from the first message.

You can preview exactly what it will write by running burrow agent claude without install. Nothing lands until you add that word.

If you are driving everything yourself for now, you can skip this step and come back to it later. The rest of this guide works the same either way, because your agent runs the same operations you are about to run by hand.

Step 3: build and push your app image

Burrow deploys your app by image reference. That means you build a container image with your own tooling, push it somewhere your cluster can pull from, and hand Burrow the reference. Your code never travels through Burrow itself, it travels the normal way, through a registry.

docker build -t ghcr.io/you/web:1.0.0 .
docker push ghcr.io/you/web:1.0.0

One habit worth forming right now: give every build a fresh, climbing version tag. Use 1.0.0, then 1.0.1, then 1.1.0, never a floating tag like latest. A unique tag is what makes a rollback meaningful later, because "the previous version" has to actually name a different image.

If your registry is private, tell Burrow how to pull from it once:

burrow registry login ghcr.io

You run that yourself, at your own terminal, because it involves a credential. It is a one time setup, not something you repeat per deploy.

If your image needs a specific start command rather than the one baked into it, you can pass it after a -- on the deploy line. Everything after the -- becomes the command the container runs:

burrow app deploy web --image ghcr.io/you/web:1.0.0 -- ./server --port 8080

Most images already declare their own entrypoint, so you will not need this on day one. It is here for the case where one image can run as a web server or a worker depending on the command, and you want to name which.

A quick word on config and secrets

Most apps need a few settings to boot: a port, a feature flag, a database URL. Burrow keeps two kinds separate, and it is worth setting them before your first deploy so the app comes up clean.

Ordinary, non sensitive config goes in with config set:

burrow app config set web LOG_LEVEL=info
burrow app config set web PORT=8080
burrow app config list web

Anything sensitive, an API key, a token, a password, goes in as a secret instead:

burrow app secret set web STRIPE_KEY

Notice there is no value on that line. Burrow prompts for it at your terminal so the secret never sits in your shell history or scrolls up your screen. You set secrets yourself, by hand, at your own machine. This is the one part your agent deliberately cannot do: it can confirm that a secret key exists, but it can never read or set the value. Sensitive material stays with the human, on purpose.

Both config and secrets are stored per app and wired into the workload for you, so your code just reads them as ordinary environment variables.

Step 4: deploy it

Now the fun part:

burrow app deploy web --image ghcr.io/you/web:1.0.0

Burrow takes the reference, rolls out the workload, and reports back:

deployed web as release 35241b6b... (image ghcr.io/you/web:1.0.0, 1 replica, deployed)

That is a real deploy. Your app is running on your cluster, self healing if a process falls over, and ready to roll cleanly the next time you ship a new version. If you asked your agent to do this instead, it ran the same command through burrow-agent and read the result back to you in plain language.

Step 5: confirm it is healthy

Never trust a deploy you have not looked at. Check the status:

burrow app status web

app: web
release: 35241b6b... (image ghcr.io/you/web:1.0.0, deployed)
workload: 1/1 replicas ready, available

1/1 replicas ready, available is what you want to see. If the app is crash looping or the image failed to pull, the status says so instead of leaving you guessing, and the logs fill in the rest:

burrow app logs web

This reads the recent output straight from the running app. When something is wrong, the reason is usually right there in the last few lines, whether it is a missing environment variable or a bad config value. This is also the moment your agent shines: hand it the logs and ask what broke, and it reads them for you.

Step 6: put it on the internet, over HTTPS

Right now the app runs inside your cluster. To serve it at a real domain with a certificate, publish it:

burrow app publish web --host app.example.com --port 8080 --tls

That tells Burrow to route app.example.com to your app on port 8080 and to request an HTTPS certificate for it. Point your domain's DNS at the cluster's address, then check the whole chain:

burrow app reachability web --wait

The --wait flag polls until the app is actually live, or until it times out. Instead of a bare "up or down," it walks the chain link by link: is the route in place, is there an address to reach, has the certificate issued, does DNS resolve. If one link is not ready yet, it names that link, so "the cert has not issued yet" is a status you can read rather than a mystery you have to debug.

When it comes back green, open https://app.example.com. That is your app, live on infrastructure you own, served over HTTPS.

When the status is not green

Not every first deploy comes up clean, and that is fine, because Burrow tells you what went wrong instead of leaving you to guess. Two failures are common enough to name here.

The first is a bad image pull. If your registry is private and Burrow does not have credentials for it, the workload cannot start because it cannot fetch the image. The status says so plainly, and the fix is the one time burrow registry login from step 3. Once Burrow can pull, the workload comes up on the next deploy.

The second is the app starting and then crashing, usually because it is missing a config value or a secret it needs to boot. The status shows the workload is not settling, and the logs show you exactly why:

burrow app logs web

Nine times out of ten the last few lines name the missing piece, a database URL that is not set, a required environment variable that is blank. You set it (burrow app config set web KEY=value for ordinary config, burrow app secret set web KEY=value for anything sensitive), redeploy, and it comes up. The point is that a failed first deploy is a readable problem, not a wall.

Scaling when traffic grows

Once your app is live, running more copies of it is one command:

burrow app scale web 3

That runs three replicas behind the scenes, sharing the load, so a busy app has more hands. Scaling is a separate action from deploying, so a later deploy will not quietly reset your replica count. When you would rather Burrow adjust the number for you as load rises and falls, you can turn on autoscaling with a floor and a ceiling you set, and it scales between them on demand. Either way, you are in control of the bounds.

Running more than one environment

Sooner or later you will want a staging environment to try changes before they hit production. Burrow handles that as a first class idea rather than a second cluster you have to babysit. You add an environment, switch to it, and deploy the same way:

burrow env add staging
burrow env use staging
burrow app deploy web --image ghcr.io/you/web:1.1.0

Because you deploy by naming an image, promoting a change from staging to prod is not a rebuild, it is a redeploy of the exact same artifact:

burrow env use prod
burrow app deploy web --image ghcr.io/you/web:1.1.0

The image you proved in staging is byte for byte the image that runs in prod. You can see which environments exist with burrow env list, and you can tighten prod specifically so a deploy there has to be confirmed:

burrow guard set app.deploy confirm --env prod

After that, a prod deploy is held for your explicit sign off, while staging stays fast and frictionless. That is especially useful once an agent is proposing deploys, since it can move freely in staging and still has to ask before it touches prod.

What can go wrong, quickly answered

A short list of the questions that come up on a first deploy, and the honest answers.

The deploy says the image cannot be pulled. The registry is private and Burrow has no credentials for it. Run burrow registry login <host> once at your terminal, then deploy again.

The app deploys but the status never reaches available. It is starting and crashing, almost always because a config value or secret it needs to boot is missing. Read burrow app logs web, set the missing piece with config set or secret set, and redeploy.

I redeployed and my replica count reset. It does not. Scaling is a separate action from deploying, so a deploy keeps whatever replica count you last set. If you scaled to three, a new deploy still runs three.

A new version is bad and I need out now. Run burrow app rollback web. Burrow keeps the previous release warm, so traffic shifts back in a moment with no rebuild.

Can my agent do all of this? Yes, the operate verbs (deploy, status, logs, scale, rollback, reachability) all run through burrow-agent, the scoped surface. The exceptions are the credential steps: registry login and setting secret values stay at your own terminal, by design.

What you just did, and what you did not have to do

Look back at the six steps. You installed a system, deployed an app, checked its health, and gave it a public HTTPS address. You did not write a single line of YAML. You did not configure an ingress controller by hand, wrangle certificate renewal, or learn what a rolling update strategy is. Burrow did the Kubernetes shaped work so you could stay in the part you care about: your app, live, at a URL.

And because every one of those steps was a legible command, you can put them in a script, paste them into notes, or hand them to your agent to run. There is nothing hidden behind a button that only a dashboard knows how to press.

Do not have a cluster yet?

If you do not have a cluster at all, you do not need to spin up a managed one to get started. Burrow can turn a single plain machine into your cluster. On a fresh VPS with a couple of gigabytes of memory, put the burrow binary on the box and run the bootstrap once over your own SSH session:

# on the VPS, once
burrow cluster bootstrap

It installs everything and prints a burrow join <token> line. Run that line on your laptop, and from then on you operate the cluster from your laptop exactly as above. That path is built for the solo developer who wants their own box, not a managed platform, and does not want to become a cluster administrator to get one. A single node's public address serves your app for free, with no extra load balancer bill.

Either way, the loop from here on is the same. Build a new image with a fresh tag, burrow app deploy web --image ..., check the status, and if a release ever misbehaves, burrow app rollback web puts you back on the previous one in a moment. That is the day to day, and it stays this simple as your app grows.