Installation

Install the desktop app, download the octo CLI, run it from Docker, or build it from source.

Five ways to get Octo, in increasing order of effort: install the desktop app, download a prebuilt CLI, install it with go install, run it from Docker, or build from source.

Download the desktop app

Octo Desktop is the visual editor as a native macOS app: open a folder, edit the flows in it, run them, and point an AI assistant at the MCP endpoint it advertises. The octo runtime and the dolphin test runner are bundled inside, so there is nothing else to install.

Download Octo_mac_arm64.dmg

Open the .dmg, drag Octo to Applications, and launch it. Released builds are signed with a Developer ID certificate and notarized by Apple, so Gatekeeper lets them through on first launch.

The app opens the folder you used last, and File → Open Folder… picks a new one. Everything in it is plain YAML on disk — the same files the CLI runs, so a flow you build here runs unchanged with octo run.

Windows and Linux builds are not published yet; use the Docker editor there, which is the same editor served in a browser. See Octo Desktop for the full tour.

Download the CLI

Every release publishes a statically linked octo binary for macOS, Linux, and Windows on the GitHub releases page.

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

If Gatekeeper blocks the first run, clear the quarantine attribute with xattr -d com.apple.quarantine /usr/local/bin/octo.

Each release also ships a checksums.txt with the SHA-256 of every archive:

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

Confirm the install:

octo version# octo 0.11.7 (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

With a Go toolchain (1.27 or later), go install compiles and installs the CLI into $(go env GOPATH)/bin:

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.11.7

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 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.11.7/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 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.

Check both binaries, then run a real suite from a clone of the repository:

dolphin version
dolphin test samples/error-handling.yaml

ok   samples/error-handling_test.yaml  (charge-flowlevel)  73ms

2 passed, 0 failed, 0 errored, 0 skipped  (73ms)

From there, your first test writes one from scratch.

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 image runs your integrations only. 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 image bundles the visual editor with the runtime. 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. See the Editor Quickstart for the tour, and Docker images for what is inside each one.

Build from source

Prerequisites

Go 1.27 or later.
Task, the repository's build runner (brew install go-task on macOS).
pnpm, only for 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 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

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

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. To run octo from anywhere:

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

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

Only a source build carries your local changes; released binaries and images are cut from tagged commits by the release pipeline.

Installation

On this page