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. make install waits up to 30s for the old daemon to fully exit (then escalates to SIGKILL and waits up to another 10s) before installing, and aborts the install if it never does.

Next Steps

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