Skip to content

Getting started

Install

On macOS, use Homebrew:

brew install piotrkowalczuk/tap/zordon

On Linux, download a tarball from Releases and extract it into a directory on your $PATH:

tar -xzf zordon_<version>_linux_amd64.tar.gz -C ~/.local/bin zordon alpha tommy

If you already have a Go toolchain, this works too:

go install github.com/piotrkowalczuk/zordon/cmd/...@latest

Each option installs three binaries: zordon, alpha, and the tommy reaper. Keep all three in the same directory, and make sure that directory is on your $PATH. See Binaries and layout for why.

Check it worked:

zordon --version

Use from Claude Code (optional)

If you drive your stack from an agent, install the Claude Code plugin — it registers the zordon mcp server and a bundled skill automatically, with no .mcp.json editing.

/plugin marketplace add piotrkowalczuk/zordon
/plugin install zordon@zordon

The plugin does not bundle the binary, so you still need zordon on your $PATH from the install step above. See the install how-to for the full walkthrough.

A first stack

Create an Alphasfile in your project root — start from the simple example — then:

zordon start              # resolve, build, bring the stack up, stream logs
zordon start svc1 svc2    # bring up just these services (+ their after deps)
zordon status             # what's running across the whole chain right now?
zordon stop               # shut this level's services down
zordon workspace create x  # a parallel, isolated copy of the whole stack
zordon get <expr>         # print one resolved value (path or Go template)

zordon start returns as soon as every service is READY (so your shell is free); alpha keeps the stack running in the background until zordon stop or a kill.

Useful flags

zordon --agent              machine-friendly log format ('<ms> <src> <LEVEL> <msg>')
zordon start --services a,b bring up just a,b (+ deps); env: ZORDON_SERVICES, same as positional args
zordon start --failfast     abort bringup and shut down on first failure (default on)
zordon start --alpha-log P  where alpha appends its own log
zordon start --timeout 60s  max wait for alpha to come up & finish bringup

Next

  • Concepts — the handful of ideas the rest builds on
  • Alphasfile — every field, with examples
  • Services — per-toolchain build/run: Go, Rust, Ruby, Node.js