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:
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 xstands 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 startreturns 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 cleanfor teardown. - Agent-friendly output.
--agentemits terse, structured logs; output is kept signal-dense because when a model reads your logs, tokens are the budget. - MCP server.
zordon mcpexposes every command — and every provision — as MCP tools, so an agent can drive the whole stack. → docs - Guardrails for agents. The
Alphasfileplus the MCP surface form a narrow, declared interface between agent and stack — it runs the named provisions you defined, not an open shell, so it can't improvise its way around your setup. - No runtime dependencies. Three static Go binaries —
zordon,alpha,tommy— and nothing else to install, image, or register.
Documentation
Full docs: https://zordon.io
(source in docs/, built with MkDocs Material).
- Alphasfile — the manifest: services, source pointers, readiness, logs
- Dynamic configuration — the DAG, helpers,
self, cross-service refs - Workspaces — parallel, isolated copies of the whole stack
- Federation — chained Alphasfiles, shared infra,
zordon sudo - MCP server — drive zordon (and its provisions) from an agent over MCP
- Install the Claude Code plugin — zero-config setup via
/plugin install
Installation
Homebrew (macOS):
A release tarball (macOS and Linux, arm64 and amd64) from
Releases:
Or from source, if you have a Go toolchain:
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:
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:
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:
Or add it to your client's MCP config (e.g. .mcp.json):
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:
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.