Installation

There are four ways to get Octo, in increasing order of effort: download a prebuilt CLI for your platform, install it with go install, run it from Docker with no install at all, or build from source.

Download the CLI

Every release publishes a self-contained octo binary for macOS, Linux, and Windows on the GitHub releases page. There is no runtime dependency — the binary is statically linked, so there is nothing to install alongside it.

# Apple Silicon; use darwin_amd64 on an Intel Mac.curl -fsSL -o octo.tar.gz \https://github.com/juancavallotti/octo/releases/download/v0.4.2/octo_darwin_arm64.tar.gztar -xzf octo.tar.gzsudo mv octo /usr/local/bin/octo

macOS quarantines binaries downloaded from the internet. If Gatekeeper blocks the first run, clear the attribute with xattr -d com.apple.quarantine /usr/local/bin/octo.

# x86-64; use linux_arm64 on arm.curl -fsSL -o octo.tar.gz \https://github.com/juancavallotti/octo/releases/download/v0.4.2/octo_linux_amd64.tar.gztar -xzf octo.tar.gzsudo install -m 0755 octo /usr/local/bin/octo

# x86-64; use windows_arm64 on arm.Invoke-WebRequest -Uri https://github.com/juancavallotti/octo/releases/download/v0.4.2/octo_windows_amd64.zip -OutFile octo.zipExpand-Archive octo.zip -DestinationPath .# Move octo.exe somewhere on your PATH.

Each release also ships a checksums.txt with the SHA-256 of every archive. Verify a download before installing it:

curl -fsSL -O https://github.com/juancavallotti/octo/releases/download/v0.4.2/checksums.txtsha256sum --ignore-missing -c checksums.txt

Confirm the install:

octo version# octo 0.4.2 (built 2026-06-18T22:31:23Z)

Continue to Your First Flow, or read Running Flows Locally for run, invoke, and eval in depth.

Install with go

If you already have a Go toolchain (1.25 or later), go install fetches, compiles, and installs the CLI into $(go env GOPATH)/bin — no clone, no release archive:

go install github.com/juancavallotti/octo/runtime/octo@latest

Pin a release instead of tracking @latest by naming its tag:

go install github.com/juancavallotti/octo/runtime/octo@v0.4.2

Make sure $(go env GOPATH)/bin is on your PATH, then confirm with octo version.

Binaries installed this way do not carry the build date that the released archives do, so octo version reports the version without it.

Install dolphin

dolphin is octo's companion test runner: it drives the octo CLI to unit-test an integration. It ships from the same release, in the same versions, through the same two channels:

# A prebuilt binary (Apple Silicon; swap the platform as above).curl -fsSL -o dolphin.tar.gz \https://github.com/juancavallotti/octo/releases/download/v0.4.2/dolphin_darwin_arm64.tar.gztar -xzf dolphin.tar.gzsudo mv dolphin /usr/local/bin/dolphin# Or, with a Go toolchain:go install github.com/juancavallotti/octo/runtime/dolphin@latest

dolphin runs your tests by running the real octo, so it has to find one. It looks in three places and stops at the first hit:

$OCTO_PATH — the binary itself, or a directory holding it
./octo — in the current directory
octo — on your PATH

$OCTO_PATH is an override, not a hint. When it is set but does not name a runnable octo, dolphin fails instead of falling back to the other two — testing against a different build than the one you asked for is a worse outcome than not testing at all.

Run from Docker

Two public images on Docker Hub, both multi-arch (linux/amd64 and linux/arm64) and published on every release. Neither needs a cluster.

The runtime alone — runs your integrations, nothing else. Mount a directory of flow YAML at /etc/octo/integrations; the runtime loads every .yaml/.yml in it and serves HTTP sources on port 8080 by default:

docker run -p 8080:8080 -v "$PWD:/etc/octo/integrations" juancavallotti/octo-runtime

The editor — the visual editor with the runtime bundled, for building flows rather than just running them. Flow YAML is read and written in the directory you mount:

docker run -p 3000:3000 -v "$PWD:/work" juancavallotti/octo

Open http://localhost:3000 and start editing. See the Editor Quickstart for the tour, and Docker images for what is inside each one.

Build from source

Prerequisites

Go 1.25 or later — the runtime is a single Go module.
Task — the repository's build runner (brew install go-task on macOS).
pnpm — only needed if you plan to work on the web apps (editor, platform, docs). Not required for the CLI.

Build the CLI

Clone the repository

git clone https://github.com/juancavallotti/octo
cd octo

Build the binary

task runtime:build

This compiles both CLIs and writes them to bin/octo and bin/dolphin, stamping the build date into each. task runtime:build:octo builds just the runtime.

Verify the build

bin/octo version

You should see the version and build date:

octo 0.4.2 (built 2026-06-18T22:31:23Z)

The version is the release you built; the build date is stamped at link time, so yours will differ.

Add it to your PATH (optional)

The docs refer to the binary as bin/octo from the repo root. If you want to run octo from anywhere, copy or link it onto your PATH:

ln -s "$PWD/bin/octo" /usr/local/bin/octo

The repo also ships runnable samples. Try one straight away with task run:sample -- hello-world.yaml, or continue to Your First Flow for the walkthrough.

A source build is the only one that carries your local changes — the released binaries and images are cut from tagged commits by the release pipeline.

Installation

On this page