Installation

Prerequisites

Before installing Cloche, make sure you have:

  • Docker — Cloche runs every agent task inside a container. Install from docs.docker.com.
  • Git — result extraction relies on git worktrees, so your project must be a git repository.

Build from Source

This is the primary and fully-supported installation method.

git clone https://github.com/swordsmanluke/cloche.git
cd cloche
make install

make install does the following in one step:

  1. Compiles three binaries: cloche, cloched, and cloche-agent
  2. Builds the cloche-agent:latest Docker image
  3. Installs the binaries to ~/.local/bin/
  4. Starts the cloched daemon

Build requirement: Go 1.25 or later.

Add to PATH

export PATH="$HOME/.local/bin:$PATH"

Add this to your shell’s rc file (~/.bashrc, ~/.zshrc, etc.) so it persists across sessions.

Custom install prefix

To install to a system-wide location instead of ~/.local:

make install PREFIX=/usr/local

Binaries will land in /usr/local/bin/.

go install

You can install the binaries directly with go install, but you will still need to build the Docker image separately.

go install github.com/swordsmanluke/cloche/cmd/cloche@latest
go install github.com/swordsmanluke/cloche/cmd/cloched@latest
go install github.com/swordsmanluke/cloche/cmd/cloche-agent@latest
go install github.com/swordsmanluke/cloche/cmd/clo@latest

clo is a lightweight CLI available inside containers for reading and writing the daemon’s KV store.

This places the binaries in $GOPATH/bin (or $HOME/go/bin by default).

Then build the Docker image:

git clone https://github.com/swordsmanluke/cloche.git
cd cloche
make docker-build

Pre-built Release Binaries (Planned)

Pre-built binaries are not yet available. This section documents the planned installation method.

Once releases are published, you will be able to install on Linux (amd64) with:

curl -sSL https://github.com/swordsmanluke/cloche/releases/latest/download/cloche-linux-amd64.tar.gz \
  | tar -xz -C ~/.local/bin/

You will still need to build the Docker image. Clone the repo and run make docker-build as described in the go install section above.

Watch the releases page for availability.

Homebrew (Planned)

Homebrew support is not yet published. This section documents the planned tap.

brew tap cloche-dev/tap
brew install cloche

You will still need the Docker image — the formula will print post-install instructions for building or pulling it.

Verifying the Installation

Confirm the binaries are installed and accessible:

cloche --version

Start the daemon if it isn’t already running:

cloched &

Verify the Docker image is present:

docker images cloche-agent

If it’s missing, build it:

make docker-build

Finally, confirm the CLI can reach the daemon:

cloche list

A blank list (or any output without a connection error) means everything is working.

Upgrading

Pull the latest changes and reinstall:

cd cloche
git pull
make install

This stops the running daemon, rebuilds all binaries and the Docker image, installs the new binaries, and restarts the daemon automatically.

Next Steps

  • Quickstart — scaffold a workflow and run your first agent task
  • Learn Cloche — full DSL reference, workflow configuration, and tutorials