Get started

Install

What you need to run Orchestrator Zero, and how to build it.

For: People installing a server or node.

Before the first public release, build the server and node from source. For a local trial, use the quickstart container or follow the quickstart. A running edge can install and join additional nodes.

In this guide

  • Prepare the Linux sandbox: Set up bubblewrap and the distribution's sandbox profile before starting a Linux node that needs tier 1.

Two binaries

BinaryWhat it isRuns on
orchestrator-zeroThe server (management, edge and embedded Temporal) and the operator CLI. A static Go binary.Linux, macOS and Windows, amd64 and arm64
orchestrator-zero-nodeThe node. A static Go binary that installs uv, a managed Python and the agent runtime on first start.Linux, macOS and Windows, amd64 and arm64

Windows on arm64 runs nodes with x86_64 Python under emulation, because Temporal's Python SDK has no arm64 build for Windows. Development and testing happen on Linux; macOS and Windows run the node's tests once a month.

Try it with Docker

Terminal
make image-quickstart
docker run --rm -p 8443:8443 orchestrator-zero:quickstart

starts a dev server, the web UI, a node and a sample plugin in one container, and prints where to sign in. For a small team, deploy/compose/compose.yaml runs PostgreSQL, a server and a node. See Docker.

Build from source

Two scripts are called install.sh. The release's installs the server or a node from a release's files, and comes with the first public release (Releases); until then there are no published binaries or images. The edge's (https://<edge>:7443/install.sh, and install.ps1 on Windows), served by the server’s edge role, installs a node from that edge and joins it (Join nodes). To run a server before the first release, build both binaries and the runtime bundle from the repository:

Terminal
git clone https://github.com/orchestrator-zero/orchestrator-zero.git
cd orchestrator-zero
make doctor                  # checks Go 1.27, uv 0.12 and buf 1.73
make build                   # bin/orchestrator-zero and bin/orchestrator-zero-node
make web build               # the same, with the web UI built into the server (needs Node.js 24)
make dist                    # dist/: the node binary for each platform, the runtime bundle and the toolchain, for the edge to serve
make images                  # container images of the server and the node, built locally (needs Docker)

make build never needs Node.js, so the server it builds has the web UI only when make web ran first. Without it, make build ends with a line that says so, and the server answers the web UI's address with a page that says how to build it in: make web build, then start the server again. The CLI and the APIs work either way.

With dist/ next to the server's bin/ folder (or server start --dist-dir), the edge serves new nodes everything they need: the web UI shows a single command that installs and joins a node and runs it as a service, on Linux, macOS or Windows (see Join nodes and Nodes as services). Without it, copy bin/orchestrator-zero-node to the machine and give run a bundle with --runtime-bundle (from make runtime-bundle).

What a node needs

  • Outbound access to the edge on ports 7233 (Temporal, mTLS) and 7443 (HTTPS). Nothing inbound.
  • Disk for uv, Python, Node.js (only when a plugin uses npm packages) and plugin environments, in the node's data directory (default ~/.local/share/orchestrator-zero-node).
  • On Linux, glibc 2.28 or newer (RHEL 8, Debian 10, Ubuntu 20.04 and later); on macOS, 11 or newer. The edge's toolchain mirrors only wheels those install.
  • Nothing else, when the edge mirrors the toolchain: make dist (or make toolchain) puts uv, Python, the runtime's packages and Node.js in dist/toolchain, and nodes install them from the edge. Without it a node downloads them from GitHub, Astral, PyPI and nodejs.org the first time. oz0-node run --offline never falls back to the internet.
  • Access to PyPI and npm while plugins install their own dependencies, or, on an offline node, their Python packages in the edge's toolchain (oz0-node toolchain fetch --plugin <folder>). A cluster with no way out installs from an offline folder: the edge then serves PyPI and npm mirrors of its packages, and offline nodes take every plugin package from them.
    Harness binaries are not mirrored and still download. Outbound connections lists every host a cluster may reach, and how to turn each off; nothing phones home.
  • For sandbox tier 1, which harness sessions and webhook jobs use: on Linux, bubblewrap and unprivileged user namespaces; macOS needs nothing to install, since Seatbelt is part of it, but the current node-data profile fix has been checked only on Linux and still needs a Mac run (tested status). Both install scripts set Linux up when they run as root, and oz0-node sandbox check says what the machine runs (see Sandbox tier 1 on Linux).

What a cluster needs

These requirements describe the default combined server: management, edge and embedded Temporal in one process. Separate roles have different database, storage and key requirements.

  • PostgreSQL 13 to 16, reachable from every server, with max_connections of at least 100 per server.
  • A copy of the master key file on every server.
  • Ports open between servers for Temporal's own traffic (7234 to 7236 and 7239, and 6933 to 6935 and 6939), and port 8443 for operators. See Ports.

For trying things out, dev mode needs none of this: one process on SQLite. See Dev mode.

Next

Copyright © 2026