Octov0.11.17
Standalone Editor

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

PlatformDownload
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

  1. Choose Container → Build and Run….
  2. 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.
  3. Keep or change the Image name (octo/<folder>:dev by default).
  4. 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 outWhy
.env.dev, .env at the top of the folderLocal credentials. Building them in would publish them on push.
.octo/The editor's own metadata.
*_test.yaml, *_test.ymlDolphin test suites, which the runtime skips.
Dockerfile, .dockerignore at the top of the folderGenerated for the build.
.git/, node_modules/, .DS_Store, anywhereNot part of the integration.
Symbolic links that point outside the folderThey 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:dev

Push to a registry

  1. Choose Container → Push Image….
  2. Enter a target in Push to, such as ghcr.io/<you>/orders:1.0.0.
  3. 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.io

To try it without an account, start a local registry and push to localhost:5055/octo/orders:dev:

docker run -d -p 5055:5000 registry:2

Port 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

  1. 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.
  2. 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.
  3. Confirm the folder. It defaults to a folder named after the integration in your Projects folder, ~/Documents/Octo unless 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:

MarkMeaningClicking 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.
DownloadThe 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: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, 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, octopaasinside 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/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.

On this page