Installation

Zester ships as a single static Go binary with zero external dependencies. No Python runtime, no pip packages, no database.

Docker Compose (Playground)

The fastest way to try Zester is with the Docker Compose playground. No Go installation required — just Docker.

git clone https://github.com/ptorbus/zester.git
cd zester
docker compose up -d

This starts a complete Zester cluster:

Service	Role
`init`	Bootstraps auth credentials, NATS server config, and copies example states/settings, then exits
`nats`	External NATS server with JetStream (port 4222)
`master`	Zester master (connects to NATS as a client)
`web-01`	Peel agent (auto-enrolls on startup)
`web-02`	Peel agent (auto-enrolls on startup)
`db-01`	Peel agent (auto-enrolls on startup)
`admin`	Admin container with `zester` CLI for enrollment and management

Peels start without credentials and auto-enroll via the master's HTTPS API. Approve pending enrollments from the admin container, then run commands:

# Approve all pending enrollments
docker compose exec admin sh /playground/auto-approve.sh

# Run a command on all peels (after enrollment)
docker compose exec admin zester '*' cmd.run 'hostname'

# Apply a state
docker compose exec admin zester 'web-01' state.apply hello

# Manage a file directly
docker compose exec admin zester 'db-01' file.managed /tmp/test.txt content="hello"

See the Quick Start for a full walkthrough.

System Requirements

Requirement	Minimum	Recommended
OS	Linux (amd64, arm64), macOS, Windows	Linux amd64
Go	1.25+ (build from source only)	Latest stable
Memory	128 MB (peel), 512 MB (master)	256 MB (peel), 2 GB (master)
Disk	50 MB (binary)	1 GB+ for JetStream storage on master
Network	TCP port 4222 (NATS)	TLS-capable network between master and peels

Build from Source

Zester requires Go 1.25 or later. Building from source gives you the latest development version.

Install Go

brew install go

sudo apt update && sudo apt install -y golang

wget https://go.dev/dl/go1.25.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.25.5.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

Build Zester

Clone the repository and build all binaries:

git clone https://github.com/ptorbus/zester.git
cd zester
go build -o bin/zester ./cmd/zester
go build -o bin/zester-master ./cmd/zester-master
go build -o bin/zester-peel ./cmd/zester-peel

Or install the CLI directly to your $GOPATH/bin:

go install github.com/ptorbus/zester/cmd/zester@latest
go install github.com/ptorbus/zester/cmd/zester-master@latest
go install github.com/ptorbus/zester/cmd/zester-peel@latest

Three binaries

Zester produces three separate binaries:

zester — CLI tool for administration and queries
zester-master — The master control plane (connects to external NATS)
zester-peel — The managed node agent

Binary Releases

Pre-built binaries are available on the GitHub Releases page.

curl -LO https://github.com/ptorbus/zester/releases/latest/download/zester-linux-amd64.tar.gz
tar xzf zester-linux-amd64.tar.gz
sudo mv zester zester-master zester-peel /usr/local/bin/

curl -LO https://github.com/ptorbus/zester/releases/latest/download/zester-linux-arm64.tar.gz
tar xzf zester-linux-arm64.tar.gz
sudo mv zester zester-master zester-peel /usr/local/bin/

curl -LO https://github.com/ptorbus/zester/releases/latest/download/zester-darwin-arm64.tar.gz
tar xzf zester-darwin-arm64.tar.gz
sudo mv zester zester-master zester-peel /usr/local/bin/

curl -LO https://github.com/ptorbus/zester/releases/latest/download/zester-darwin-amd64.tar.gz
tar xzf zester-darwin-amd64.tar.gz
sudo mv zester zester-master zester-peel /usr/local/bin/

Verify Installation

After installing, verify that all binaries are available:

zester version

Expected output:

zester v0.1.0 (commit: abc1234, built: 2026-02-10T00:00:00Z)

Check each binary:

zester-master --help
zester-peel --help

Shell completion

Zester uses Cobra for its CLI, which supports shell completions. Generate them with:

zester completion bash > /etc/bash_completion.d/zester

zester completion zsh > "${fpath[1]}/_zester"

zester completion fish > ~/.config/fish/completions/zester.fish

Directory Layout

Zester follows a conventional layout for configuration and data:

Path	Purpose
`/etc/zester/master.yaml`	Master configuration file
`/etc/zester/peel.yaml`	Peel configuration file
`~/.zester/config.yaml`	CLI configuration (user-level)
`/var/lib/zester/jetstream/`	JetStream storage (master)
`/srv/zester/states/`	State files (.zy)
`/srv/zester/settings/`	Settings files (.zy)
`/etc/zester/peel.key`	Peel nkey seed file (0600 permissions)

Peel key permissions

The peel nkey seed file (peel.key) and credentials file (.creds) must have 0600 permissions. Zester writes these files with restricted permissions by default, but verify after any manual edits.

Next Steps

With Zester installed, head to the Quick Start to set up your first master and peel.

On this page