Zordon
The local stack your inner loop runs against — databases, brokers, proxies and services as fast, disposable host processes, declared once and supervised together. No containers.
Zordon is a supervisor for the local stack your code runs against — the databases, brokers, proxies and services that have to be alive for your code to be exercised for real.
It runs them as ordinary host processes instead of containers, declared once in an Alphasfile and supervised together, so standing the stack up, duplicating it, and throwing it away are all cheap.
Three goals shape every decision.
Low latency — standing the stack up and re-running sit inside the loop, not around it; iteration shouldn't wait on infrastructure.
Resourcefulness — per-stack overhead stays small enough that many agents run side by side, each with a stack real enough to evaluate against rather than a wall of mocks.
Guardrails — the Alphasfile doubles as a contract, so the MCP server hands an agent only a narrow, declared surface: bring the stack up, inspect it, run a provision you named, and work through that interface instead of improvising against the host.
Why not containers?
Code is increasingly written in a loop — change something, run the real stack against it, read the result, go again, hundreds of times an hour.
Containers buy isolation by paying full cold-start and idle-overhead cost on every run: right for production, wasteful for a loop.
Zordon takes the other side, recovering isolation from per-run workspaces instead of images — so a second stack beside yours, or a tenth, is a non-event.
Declare the whole stack in one Alphasfile:
service "go" "nats" {
git {
url = "github.com/nats-io/nats-server"
tag = "v2.14.0"
}
vars = { client = net::pickport() } # grab a free port, no clashes
arguments { values = { main = { p = self.vars.client } } }
}
zordon start # resolve, build, bring it up, stream logs until everything is READY
Features
- No containers, no daemon. Your databases, brokers, proxies and services run as plain supervised host processes — nothing to image, mount or register.
- Polyglot toolchains. Go, Rust, Ruby, Node.js and Java (Maven/Gradle) services built straight from a git URL or local source; native packages (Redis, PostgreSQL, etcd, …) provisioned through mise.
- One manifest. The whole stack — source, build, run, env, readiness, logs — declared in a single
Alphasfile.
- Dynamic configuration as a graph. Values are functions, not strings:
net::pickport() picks a free port, fs::tmp()/fs::hash() give per-run paths, and services reference each other (service.go.caddy.vars.http) with zero hardcoded wiring. → docs
- Workspaces.
zordon workspace create x stands up a second, fully isolated copy of the entire stack — own ports, own dirs — an agent's sandbox beside yours, no port-mapping. → docs
- Federation. Alphasfiles chain by directory position: a project sits below shared infra instead of importing it. Move it in the tree and its environment recomputes. → docs
- Readiness-aware bringup. HTTP and exec readiness checks over a dependency graph;
zordon start returns the moment every service is READY, then keeps the stack alive in the background.
- Convergent re-runs. Re-running costs only what actually changed — no blanket teardown and rebuild.
- Provisions. One-off setup (migrations, seeding, topic creation) declared per service, run on demand, with
zordon clean for teardown.
- Agent-friendly output.
--agent emits terse, structured logs; output is kept signal-dense because when a model reads your logs, tokens are the budget.
- MCP server.
zordon mcp exposes every command — and every provision — as MCP tools, so an agent can drive the whole stack. →
Documentation
Full docs: https://zordon.io
(source in docs/, built with MkDocs Material).
Installation
Homebrew (macOS):
brew install piotrkowalczuk/tap/zordon
A release tarball (macOS and Linux, arm64 and amd64) from
Releases:
tar -xzf zordon_<version>_<os>_<arch>.tar.gz -C ~/.local/bin zordon alpha tommy
Or from source, if you have a Go toolchain:
go install github.com/piotrkowalczuk/zordon/cmd/...@latest
Every variant installs the same three binaries — zordon, alpha, and
the tommy reaper. Keep them in one directory and make sure that
directory is on your $PATH: zordon finds alpha via $PATH, and
alpha finds tommy only as a sibling of its own executable. See
Binaries and layout.
Quick start
Create an Alphasfile (see examples/simple), then:
zordon start # spawn alpha, push config, stream bringup logs
zordon status # what's running across the whole chain right now?
zordon stop # ask alpha to shut its children down and exit
zordon clean # run each provision's clean teardown (stack stopped)
zordon workspace create x # a parallel, isolated copy of the stack
See the docs for everything else.
Use with Claude (MCP)
zordon mcp runs an MCP server, over stdio by default or over HTTP with --transport=http.
It exposes every zordon command — and every provision — as a tool, so an agent can drive your stack and run provisions on demand.
The fastest path is the Claude Code plugin — no manual config:
/plugin marketplace add piotrkowalczuk/zordon
/plugin install zordon@zordon
This registers the zordon mcp server and a skill nudging the agent toward it automatically; see the install how-to.
For other MCP clients, or without the plugin:
The MCP client launches the server; you don't run zordon mcp yourself.
With Claude Code, register it from your project directory:
claude mcp add zordon -- zordon mcp
Or add it to your client's MCP config (e.g. .mcp.json):
{ "mcpServers": { "zordon": { "command": "zordon", "args": ["mcp"] } } }
The server resolves the chain from its working directory, so launch the client from the project tree (or pass -e ZORDON_HOME=…).
Provisions run inside the live alpha, so zordon start first — or let the agent call the start tool.
To let an agent confined to a container or sandbox drive a host-side stack, serve it over HTTP instead — the client then needs only a URL, with no zordon binary inside the box:
zordon mcp --transport=http --listen 127.0.0.1:7391
See the how-to; note the endpoint is not authenticated yet.
The server advertises its purpose to the agent via MCP instructions (when to reach for these tools), so it should pick them up on its own.
To nudge it harder in a zordon-managed repo, add a line to your CLAUDE.md (or AGENTS.md): "this project's local stack is managed by zordon — use the zordon MCP tools to bring it up, inspect it, and run provisions."
See the zordon mcp reference and how-to.
License
GNU General Public License v3.0,
see LICENSE.md.
