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 four binaries: cloche, cloched, cloche-agent, and clo
  2. Builds the cloche-agent:latest Docker image
  3. Installs cloche, cloched, and cloche-agent to ~/.local/bin/ (clo is baked into container images, not installed to the host)
  4. Starts the cloched daemon

Build requirement: Go 1.25.3 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 and asking the user questions mid-run (clo ask).

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

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