Octo Desktop
Download the macOS app: the visual editor, the runtime, and the test runner in one install.
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. So is octopaas, the platform's CLI, which the app
uses to pull integrations from the platform, push them back and deploy them.
Download
| Platform | Download |
|---|---|
| macOS (Apple Silicon) | Octo_mac_arm64.dmg |
| macOS (Intel) | Octo_mac_x64.dmg |
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.
Windows and Linux builds are not published yet. On those platforms run the Docker editor, which is the same editor served in a browser.
One folder at a time
The app opens the folder you used last; File → Open Folder… picks another.
A folder is one project: its *.yaml files are the config files the runtime
merges into one integration, and the editor's file switcher moves between them.
Everything in it is plain YAML on disk — the same files the CLI runs, so a
project you build here runs unchanged with octo run --config <folder>, 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.
Terminal
The console has a Terminal tab, which works like VS Code's integrated terminal.
It runs your login shell in the open folder, with the app's octo and dolphin
first on PATH. These are the binaries the editor itself runs, including any you
chose in Settings. So octo validate --config . or dolphin test in the terminal
checks exactly what the editor checks.
- Press Ctrl + `, or choose View → Terminal, to show the terminal. Press it again from inside the terminal to hide the console.
- Press Ctrl + Shift + `, or choose View → New Terminal, to start another shell. Each one is listed on the right of the tab; hover a row and click its bin icon to end it.
- Switching tabs or collapsing the console keeps your shells and their scrollback. Opening another folder or quitting the app ends them.
The shell reads your usual startup files, so Homebrew and anything else they set up
are on PATH. In zsh and bash the app's binaries go in front after those files have
run, so an octo you installed yourself does not shadow the editor's. Other shells,
such as fish, run your configuration after the app sets PATH, so anything it
prepends comes first. TERM_PROGRAM is Octo, if your prompt wants to tell this
terminal apart.
The Terminal tab is only in the desktop app. The Docker editor runs in a browser, which has nowhere to start a shell.
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.
Connect one MCP client per app. The endpoint has no sign-in, so it cannot tell two clients apart: they share one run, and a second client starting or stopping an integration does so under the first one's feet.
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.
Containers
The Container menu turns the open folder into a container image, built on the
published juancavallotti/octo-runtime image.
You can run that image on your machine, push it to a registry, or export a
Dockerfile and build it somewhere else. The image is the whole folder, because the
runtime merges every *.yaml in its config directory — the same folder
octo run --config <folder> reads.
Building, running and pushing use your own docker CLI: Docker Desktop, OrbStack,
Colima or Rancher Desktop all work, with whatever context and registry logins it
already has. When docker is not installed, or its daemon is not running, the menu
says so and only Export Dockerfile… is available. Start Docker and come back to
the app; Octo checks again whenever its window regains focus.
Build and run
- Choose Container → Build and Run….
- Pick a Runtime version. The list holds every published release plus the versions you have already pulled. It starts on the version the editor itself runs; an older one may reject blocks or settings the editor lets you write.
- Keep or change the Image name (
octo/<folder>:devby default). - Click Build & Run. Unsaved edits in the editor are saved first.
The container is named octo-<folder> and publishes on 127.0.0.1 only. Its row
under Running from this folder shows the host port of its HTTP source; Open
loads it in your browser, Logs follows its output, Remove deletes it.
Hover the port to see its health URL, which serves /healthz and /readyz.
Running again offers to replace the previous container. Containers keep running
after you quit Octo, and the window lists them the next time you open it.
What goes into the image
Every file in the folder, except:
| Left out | Why |
|---|---|
.env.dev, .env at the top of the folder | Local credentials. Building them in would publish them on push. |
.octo/ | The editor's own metadata. |
*_test.yaml, *_test.yml | Dolphin test suites, which the runtime skips. |
Dockerfile, .dockerignore at the top of the folder | Generated for the build. |
.git/, node_modules/, .DS_Store, anywhere | Not part of the integration. |
| Symbolic links that point outside the folder | They could pull in any file on your machine. |
Env files in subfolders, and env files with other names such as .env.prod, are
included: an integration that declares them under resources.env needs them in
the image. Keep secrets out of those files if you plan to push the image.
A local run passes .env.dev with --env-file, so the container sees the same
variables the editor's runs do. Wherever else the image runs, supply the variables
your integration declares in its env: section the way that platform sets
environment variables — for example:
docker run -p 8080:8080 -e GREETING=hello octo/orders:devPush to a registry
- Choose Container → Push Image….
- Enter a target in Push to, such as
ghcr.io/<you>/orders:1.0.0. - Click Build & Push. The image is built, tagged as the target, and pushed.
Remote registries use docker's own credentials, so log in once from a terminal first:
docker login ghcr.ioTo try it without an account, start a local registry and push to
localhost:5055/octo/orders:dev:
docker run -d -p 5055:5000 registry:2Port 5000 is avoided because macOS's AirPlay Receiver usually holds it. The last
few targets you pushed to are offered in the field next time.
Export a Dockerfile
Container → Export Dockerfile… writes the folder's files and a Dockerfile into
a new folder you choose. Docker is not needed. Build that folder anywhere:
docker build -t orders .The Dockerfile only copies the files onto the runtime image; it has no RUN steps,
because the runtime image has no shell.
The platform
The Platform menu, the folder picker and the Platform window connect the
open folder to an Octo platform. You pull an integration into a
folder, edit it here, push it back, freeze versions and deploy them, then follow
what the deployment logs. The app does all of this with the bundled octopaas CLI,
so everything it does, the CLI in your terminal can do too.
Installations
An installation is a platform you work with: a name and its API's address. Open
Platform → Installation → Manage Installations… to add one, sign in to it with
your browser, or give it an API key instead. You can work with several, such as a
local one and production. These are the octopaas CLI's own profiles, kept in
~/.octopaas, so a sign-in here is a sign-in in the terminal, and the other way
round.
One installation is the current one. Switch it under Platform →
Installation, or in the Platform window's header. It is the CLI's current
profile too, so a terminal that does not pass --profile follows the switch.
Platform → Sign In… and Sign Out act on the current installation.
An installation acts in one environment at a time, octo (the default) unless you choose another. When it has more than one, the Platform window's header shows an Environment picker beside the installation. The choice is saved on the CLI profile, as octopaas environments use saves it, so the terminal follows it too. The integrations you see, and the ones the editor's cloud profile lists, are the chosen environment's.
Pull an integration and open it
- Open the folder picker. Under installation cloud profile it lists the current installation's integrations; pick one that is not on this machine to pull it. For another installation, or for a version, choose Platform → Pull Integration… and continue in the Platform window.
- In the Platform window, pick the installation in the header, then choose Pull and open on an integration. Expand an integration to open one of its versions instead.
- Confirm the folder. It defaults to a folder named after the integration in your
Projects folder,
~/Documents/Octounless you change it under Installations. You can choose any new or empty folder for one pull without changing the setting.
The folder opens in the editor. It remembers which integration it is, on which
installation, in .octo/platform.json, so it always pushes and deploys to the
platform it came from, whichever installation is current. An integration already on
this machine shows Open instead of Pull and open.
Keep a folder in sync
The folder picker marks each of the current installation's integrations with how its folder here stands against it:
| Mark | Meaning | Clicking it |
|---|---|---|
| ✓ | The folder and the draft hold the same files. | — |
| ↑ | The folder has changed since it last synced. | Pushes the folder. |
| ↓ | The draft has changed on the platform. | Pulls the draft over the folder. |
| ↕ | Both have changed. | Asks whether to push or pull. |
| Download | The integration is not on this machine. | Pulls it into a new folder. |
A folder remembers the environment it was pulled from or imported into, and its pushes, versions, deploys and logs always go there, even after the installation is switched to another environment. The folder tab names that environment when it is not the default. A folder linked before environments existed belongs to the default.
A folder syncs when you pull, push or import it. A pull over an existing folder
replaces what a push would send, so a file deleted on the platform is deleted here
too; hidden files such as .git and .env stay. When a push or pull would
overwrite changes the other side has, you are asked first. A folder linked before
syncs were recorded shows ↕ until its first push or pull.
The picker keeps each installation's last list of integrations and refreshes it in place every time it opens. When the platform cannot be reached, it shows the last list, marked offline, and the marks still follow the changes you make here. A push or pull that fails turns the folder chip's icon red; hover over it to see why.
Push, versions and deploys
- Platform → Push to Platform, or ↑ in the folder picker, saves your changes and replaces the integration's draft on the platform with the folder as it is on disk. Its versions and running deployments stay as they are until you roll them out.
- This folder in the Platform window freezes the draft as a version. Leave Push this folder first on, and the version is what you see in the editor.
- Deployments lists where the integration runs, and deploys, rolls out, scales and removes deployments. A deploy without a version deploys the folder as it is now, frozen under the next tag. The output pane shows its progress until it is running.
- Logs shows a deployment's stored log, or follows its pods as they print.
A folder that is not on a platform yet goes there with Platform → Put This Folder on the Platform…, which imports it as a new integration and links it.
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:8477That 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, dolphin and octopaas inside the
app, and uses them unless you say otherwise. Point any of them 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 octo or dolphin restarts the editor server, because the server hands the
path to every run it starts; if flows are running you are asked first. A new
octopaas is used from its next command. 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.
If Octo cannot start its editor server, the error dialog offers Settings. That is the way back from a runtime binary that does not run.
Containers. Octo finds docker on your PATH and in the usual install
locations (Homebrew, Docker Desktop, OrbStack, Rancher Desktop). Settings shows
which one it found and whether its daemon is running; Choose… points Octo at a
different one, and Find Automatically goes back to searching.
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
| Path | |
|---|---|
| Application state, endpoint record | ~/Library/Application Support/Octo |
| Server log | ~/Library/Logs/Octo/server.log |
Editor server, octo, dolphin, octopaas | inside Octo.app/Contents/Resources |
Links the terminal puts on PATH | ~/Library/Application Support/Octo/term-bin |
| Installations and their sign-ins | ~/.octopaas, shared with the octopaas CLI |
| A folder's integration on the platform | <folder>/.octo/platform.json |
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/releaseA 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.