DEV Community: Shiva Kadiri

If You Can't Run It Local, You're Not Ready to Deploy

Shiva Kadiri — Wed, 15 Jul 2026 08:05:15 +0000

I'm big on developer experience.

As a leader, I want my team to be self-sufficient and handle any edge cases — without waiting on me, a shared staging box, or the one person who "knows how the env works."

DX, for me, is operational: short feedback loops, reproducible failures, and a documented path from clone to a working critical path. When that path is missing, engineers spend cycles on VPN access, shared credentials, and "works on staging" instead of on the bug. Friction compounds. Clarity compounds faster. The sharpest test I know of that clarity is simple:

If you can't run it local, you're not ready to deploy.

Deploy theater

Plenty of teams ship every day. CI is green. There is a runbook somewhere.

Then a bug shows up under a specific payload, migration, or timing window — and nobody can reproduce it without staging access, a VPN, three shared accounts, and a Slack thread titled "can someone restart the mock for me?"

That is not shipping discipline. That is deploy theater: the appearance of readiness without the ability to own a failure on your own machine.

If a new engineer — or you, on a fresh laptop — cannot bring the critical path up with a short, documented path, you do not have a deploy story. You have a hope story.

What "run it local" actually means

It does not mean cloning production into Docker Desktop. You do not need every managed service, every regional failover, every edge case of the cloud.

It means enough fidelity for the work developers actually do:

a real data store (or a close stand-in) with durable volumes
mocks for dependencies you do not own
an observability path you can hit from your app process (OTLP, logs, traces)
config, APIs, and protocol tools you can exercise without a cloud account

Local is not a toy. Local is the cheapest place to be wrong.

What dev-tools does for local run

I keep that fidelity in shivakadiri/dev-tools: a Docker Compose stack of development services. One command:

docker compose up -d

It is not an application. It is the local dependency plane — so your app (or agent, workflow, or API) can run against real-ish infrastructure on localhost instead of a shared cluster.

Bootstrap

Clone the repo, copy .env.example → .env
docker compose up -d (or docker compose up -d <service> for a subset)
Open documented URLs — Postgres on 5432, Grafana on 3000, WireMock on 9000, and the rest on fixed ports from .env

A Homepage dashboard aggregates those links so you are not hunting ports in a notes file.

What you can actually do locally

Persist and query data — shared PostgreSQL with pgvector on localhost:5432. Several services (n8n, LiteLLM, Hoppscotch) use the same instance with separate databases. pgAdmin is wired for admin work without installing a client.
Stub external APIs — WireMock Studio on 9000 (plus a port range for stubs) so you can simulate third-party failure modes, latency, and contract drift without calling production.
Emit and inspect telemetry — Grafana (otel-lgtm) with Loki, Tempo, Prometheus, and an OTel collector. Point your app at OTLP gRPC 4317 or HTTP 4318 and debug traces/logs/metrics before anything hits a cloud backend.
Automate and integrate — n8n for workflows against local services and mocks.
Call APIs end-to-end — Hoppscotch as a local API client against WireMock, your app, or anything else on the compose network / host.
Run config without Azure — Azure App Configuration emulator with anonymous UI and HMAC keys, so feature flags and config clients work offline.
Run LLM work offline — Ollama for inference, Open WebUI for chat, LiteLLM as an OpenAI-compatible proxy (/chat/completions) in front of local or cloud models.
Debug agents and MCP — A2A Inspector and MCP Inspector. When the agent or MCP server runs on the host, containers reach it via host.docker.internal (documented in the README).

Design choices that matter for DX

One shared Postgres instead of a database container per tool — fewer volumes, simpler backups, one place to reset state.
Ports and secrets in .env — predictable localhost endpoints, not random published ports.
Honest failure modes in docs — e.g. Ollama OOM-killed on Mac when Docker Desktop memory is tight; App Config emulator via platform: linux/amd64 on Apple Silicon.

That honesty is DX too. A local path that only works on a perfect day is not a local path.

I am not arguing that every team should run this exact toolbox. I am arguing that having a dependency plane you can start in minutes is how you treat developer experience as infrastructure. Steal the pattern: github.com/shivakadiri/dev-tools.

Why local fidelity makes deploy honest

When that plane runs on your laptop:

Feedback loops shrink from "wait for staging" to "change it and look" — migrations, stubs, OTLP, config.
Experiments stay isolated. Blow up a volume. Reset WireMock. Replay the bad payload. Nobody else is blocked.
You exercise the same observability path you will need in production — traces and logs on the happy path, not only during an incident.
Onboarding is a checklist, not tribal knowledge: clone → env → compose up → hit a known URL.

Deploy then becomes a promotion of something you already understand. Not a leap of faith into an environment only three people can access.

DX debt looks familiar

You will recognize the anti-patterns:

Docs that only describe cloud provisioning
Environments that exist only behind secrets and shared clusters
"Just use staging" as the default development workflow
Local setup that takes a day and a tribal knowledge session

Those are not "we'll improve DX later" items. They are release risk. Every hour a developer cannot reproduce a bug locally is an hour the incident clock runs without a controlled repro.

The bar I use

Before I trust a deploy story, I want this path to be boring:

Clone the repo
Copy .env.example (or equivalent)
docker compose up -d (or the project's equivalent one-liner)
Open a documented URL / hit a documented port
See something real working — a UI, an API, a dashboard, a successful OTLP export — in minutes, not days

If step 5 requires a ticket, a shared password in a vault nobody can find, or a cluster that is "usually up," the bar failed.

Own the failure path

I'm big on developer experience because shipping is a human system. As a leader, self-sufficiency is the goal: every engineer should be able to reproduce the weird path, poke the edge case, and own the fix. A local dependency plane — tools, docs, and compose up — is how you make that real.

If you cannot run it local, you cannot fully debug it, reproduce it, or teach it. Deploying anyway is guessing.

And guessing is the opposite of good developer experience.

I replaced homelab bash with agents — and the DX got weirdly good

Shiva Kadiri — Wed, 15 Jul 2026 07:21:59 +0000

Homelabs used to mean a folder of bash scripts, a wiki nobody updates, and one machine you are afraid to reboot.

I wanted something different: talk to the lab like a product, keep infra boring and reproducible, and make “did I break production-at-home?” a recoverable question instead of a weekend.

So I built a small multi-agent control plane on top of Proxmox, Unifi and TrueNAS — not a chatbot glued to SSH, but separate agent services behind an orchestrator, with a UI that feels closer to Cursor than to Cockpit.

This is the story of the agents, the infra, and the developer experience that made it worth doing.

Code

Everything lives in separate repos under @shivakadiri — one boundary per package:

Repo	Role
homelab-ui	Chat / History / Dashboard / Logs UI
homelab-orchestrator	Control plane + CLI (routes to agents)
homelab-unifi	UniFi agent (JSON-over-HTTP)
homelab-proxmox	Proxmox agent (A2A) + LXC provisioning
homelab-truenas	TrueNAS agent (MCP)

The shape of the system

At a high level:

UI  →  Orchestrator  →  Agent services
                          ├─ UniFi   (JSON-over-HTTP)
                          ├─ Proxmox (A2A)
                          └─ TrueNAS (MCP)

The UI never calls hypervisors or switches directly. It chats with a control plane. The control plane routes intent to the right agent. Each agent owns one domain and one protocol.

That split matters more than the LLM brand.

Agent	Repo	Protocol	Why that choice
UniFi	homelab-unifi	Langgraph remote agent	I want to leverage existing REST Apis
Proxmox	homelab-proxmox	A2A	I want maximum capabilities as agent skills
TrueNAS	homelab-truenas	MCP	My data (memories, documents), I want as deterministic as possible

The orchestrator (homelab-orchestrator) is deliberately dumb about domain logic. It is a router, health aggregator, and event bus — not a god-object that knows VLANs and ZFS and LXC presets. The UI (homelab-ui) only talks to that control plane.

If you only take one architecture idea from this post: one agent per systems boundary, one protocol per agent, one orchestrator that does not pretend to be all three.

Infra first: make the lab feel like an app platform

Agents are useless if the underlying platform is a junk drawer.

I standardized guests as Proxmox LXCs with predictable IPs and names — the unglamorous stuff that makes everything else composable:

Caddy — TLS terminator (*.klab, local CA)
AdGuard — DNS that makes homepage.klab and friends real
Homepage — human map of the lab
Postgres + pgvector — shared DB for apps that need state
Ollama + LiteLLM — local models behind an OpenAI-compatible gateway
Hoppscotch — API client aimed at those same services
Authentik — SSO / forward-auth for the pretty HTTPS surfaces
otel-lgtm — Grafana’s all-in-one OTel backend for when something lies

None of that is novel. The point is product shape: HTTPS hostnames, SSO where humans click, Bearer tokens where machines call, DNS that matches the mental model.

A concrete DX win: once litellm.klab and ollama.klab exist, agent code and API collections stop speaking raw 10.10.15.x forever. Your future self will thank you when you move a container.

Secrets are not `.env` cosplay

Every agent defaults to dry-run. Live mode pulls secrets from a pluggable store (macOS Keychain via keyring in my case). Tests use an in-memory fake store.

That sounds pedantic until you paste an API token into a compose file “just for now.”

Rules that survived contact with reality:

Dry-run by default — agents boot safely on a laptop with no credentials.
No secrets in repo-adjacent .env for prod paths — Keychain/service accounts only.
UI Plan vs Agent — Plan sends dry_run: true; Agent sends dry_run: false. Same chat, different blast radius.

The Plan/Agent toggle in the UI is the same idea Cursor has: propose vs do. Homelab operators need that muscle memory even more than app developers — there is no staging VLAN that forgives you.

Agents as services, not notebooks

It is tempting to put “the agent” in a Jupyter notebook or a single FastAPI file that SSHs everywhere.

Resist that.

Each agent is a small long-running service:

GET /health / metadata
chat or run entrypoints
monitor hooks
domain RPCs where needed (UniFi exposes live client inventory so Proxmox can auto-discover :8006 hosts on the LAN)

Proxmox discovery is a good example of agent collaboration without a shared monolith:

UniFi agent lists connected clients + IPs (live mode).
Proxmox agent probes candidates for the Proxmox API.
Orchestrator stays out of the SNMP weeds.

That is multi-agent in the useful sense: specialists with contracts, not a committee of personas arguing in one prompt.

Local LLMs without cosplaying cloud lock-in

LiteLLM in front of Ollama gives you an OpenAI-shaped endpoint on the LAN. Agents can use cloud models when you want quality, and fall back to local / deterministic stubs when you want offline or CI-friendly behavior.

The DX goal is not “never call Anthropic.” It is swap the brain without rewriting the hands — tools, secrets, dry-run, and protocols stay stable.

Developer experience is the product

Homelab projects die when the feedback loop is “reboot and pray.”

What improved the loop for me:

1. Chat as the primary interface

The UI is Chat / History / Dashboard / Logs. Routing is automatic — no “pick UniFi from a dropdown” tax on every question. Follow-ups pin session_id + agent so human-in-the-loop clarifications continue with the same specialist.

2. Observability early, not after the fire

Dropping grafana/otel-lgtm into an LXC is not “production observability.” It is a place to send traces when an agent’s tool call fails in a way logs alone will not explain. Homelabs are perfect for OTel practice because the blast radius is your evening, not your employer’s SLO.

3. API collections as living docs

Hoppscotch collections for Ollama/LiteLLM beat README curl blocks that rot. Import environments with https://…klab URLs — if you keep http://10.x while the UI is HTTPS, browsers will gift you cryptic “Network Error / Unknown cause” mixed-content failures. Ask me how I know.

4. Provisioning scripts as episodic memory

LXC presets (caddy, authentik, otel-lgtm, …) live next to the Proxmox agent. When I say “add X on homelab02,” the path is: known VMID/IP/resources → nest Docker when needed → wire DNS → Caddy → Homepage card. The agent is the operator; the script is the runbook the agent (or I) can re-run.

5. Protocol diversity on purpose

Using HTTP + A2A + MCP in one control plane sounds messy. In practice it forces clean client adapters and stops you from inventing a fourth private RPC. The orchestrator README becomes a compatibility chart, not folklore.

What I would tell past me

Start with dry-run and Keychain, not with model choice.
Give every human-facing service a hostname and TLS before you build agents on top.
Put SSO in front of UIs, not in front of machine APIs that already have Bearer tokens (or you will debug Authentik redirects instead of JSON).
Prefer small agent services over one mega-agent with every Ansible module glued on.
Treat DX as infra: Plan/Agent modes, event websockets, health endpoints, importable API collections.

Why bother?

Because the homelab is the last place many of us can still own the full stack: network → hypervisor → identity → models → UI.

Agents are having a moment in product engineering. A homelab is a ruthless playground for the same questions:

What is a safe tool?
What is a session?
Who is allowed to mutate state?
How do specialists coordinate without a shared brain?

If your agents cannot provision an LXC, respect dry-run, and explain why DNS still points at the old box — they are not ready for your day job either.

I am still iterating (always). But the lab finally feels less like a museum of containers and more like a developer platform with opinions — and chatting with it is, embarrassingly, fun.

End State

If you build something in this shape, I would love to hear what protocol split you chose — and what your first “Plan vs Agent” near-miss looked like.