Octo Desktop

Octo Desktop is the standalone editor as a native macOS app. You pick a folder, edit the flows in it, run them, and point an AI assistant at the MCP endpoint the app advertises. The octo runtime and the dolphin test runner are bundled inside, so there is nothing else to install — no Docker, no checkout, no terminal.

Download

Both links resolve to the newest release. The app is built from the same tag as the CLI archives on that release, and it ships the very binaries published there — the runner inside the app is the runner you would have downloaded.

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

One folder at a time

The app opens the folder you used last; File → Open Folder… picks another. 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, commits to git, and opens in the Docker editor.

Switching folders restarts the embedded server rather than repointing it, so a run started in one folder can never show up in another. That also means one folder is open at a time.

The MCP endpoint

The app serves the editor's own MCP endpoint, unauthenticated and local-only, exactly as the Docker image does. Its URL is on the app menu (Octo → Copy MCP Endpoint URL) and is written into the open folder as .octo/mcp-endpoint.json, so an assistant working in that directory can find it without knowing this app exists.

The port is fixed at 8477, clear of the run pools and the runtime's observability default, so an assistant configured against it stays configured across restarts and folder switches. Pin a different one with OCTO_DESKTOP_PORT.

What it actually is

An Electron shell around the same standalone editor server the Docker image runs. The app builds no editor of its own: it spawns that server as a child process and loads http://127.0.0.1:8477 in a window.

Electron main ──spawns──> standalone server ──spawns──> octo / dolphin
     │                          │
   window ──loads──> http://127.0.0.1:8477

That equivalence is the point: the environment contract is the Docker image's verbatim (OCTO_FS_DIR, OCTO_BIN_PATH, DOLPHIN_BIN_PATH, OCTO_RUN_DIR), and a bug you can reproduce in docker run is the same bug here. Everything in the editor tour, running flows, and testing in the editor applies unchanged.

Settings

Cmd + , opens Settings.

Runtime. Octo Desktop ships a matched octo and dolphin inside the app, and uses them unless you say otherwise. Point either at a binary of your own — a build from a checkout of the repository, say — to develop flows against a different runtime. Settings shows the version each one reports, so you can see which is in use at a glance.

Changing a binary restarts the editor server, because the server hands the path to every run it starts. If flows are running you are asked first. A chosen binary that has since been moved or deleted is reported in Settings and not used — the bundled one runs instead, so a detached drive costs you the setting rather than the app.

Editor. Execute flows automatically to enhance auto completion lets the editor run the flow you are working on by itself, in the background, and read the message shapes out of the run — so CEL completion knows what body.order holds before you have run anything. It is off until you turn it on.

Only flows that do nothing observable outside Octo are ever run this way. A flow that calls an API, sends a message, writes to storage or runs a program is left alone until you run it yourself; so is a flow holding a block Octo has not been told about. Nothing from these runs is shown — they leave no entry in the run history — and nothing from them is stored but field names and their types, in .octo/editor-meta.json.

Updates. Octo checks for a new version at startup and reports one if it finds it; turn that off in Settings if you would rather not. Check for Updates… in the Octo menu asks at any time, and says so when you are already up to date. An update is downloaded only if you agree, and installs the next time you quit.

Where things live

The server log is the first place to look if a window comes up empty: it is the standalone server's own output.

Building it yourself

From a clone of the repository:

task desktop:dev     # run it from the repo, rebuilding on change
task desktop:dist    # package a macOS .app + dmg into apps/desktop/dist/release

A local package is ad-hoc signed, which is enough to launch on the machine that built it. Only the release pipeline signs and notarizes for distribution. See apps/desktop/README.md for the internals.