---
title: "Install"
description: "What you need to run Orchestrator Zero, and how to build it."
canonical_url: "https://docs.oz0.ai/getting-started/install"
---
# 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](https://docs.oz0.ai/getting-started/quickstart). A running edge can install and join additional nodes.

## In this guide

- [Prepare the Linux sandbox](https://docs.oz0.ai/getting-started/install/linux-sandbox): Set up bubblewrap and the distribution's sandbox profile before starting a Linux node that needs tier 1.

## Two binaries

<table>
<thead>
  <tr>
    <th>
      Binary
    </th>
    
    <th>
      What it is
    </th>
    
    <th>
      Runs on
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        orchestrator-zero
      </code>
    </td>
    
    <td>
      The server (management, edge and embedded Temporal) and the operator CLI. A static Go binary.
    </td>
    
    <td>
      Linux, macOS and Windows, amd64 and arm64
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        orchestrator-zero-node
      </code>
    </td>
    
    <td>
      The node. A static Go binary that installs uv, a managed Python and the agent runtime on first start.
    </td>
    
    <td>
      Linux, macOS and Windows, amd64 and arm64
    </td>
  </tr>
</tbody>
</table>

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

```bash [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](https://docs.oz0.ai/fleet/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](https://docs.oz0.ai/fleet/releases#install-from-a-release)); 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](https://docs.oz0.ai/fleet/join-nodes)). To run a server before the first release, build both binaries and the runtime bundle from the repository:

```bash [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](https://docs.oz0.ai/getting-started/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](https://docs.oz0.ai/fleet/join-nodes) and [Nodes as services](https://docs.oz0.ai/fleet/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](https://docs.oz0.ai/fleet/offline-install): the edge then serves PyPI and npm mirrors of its packages, and offline nodes take every plugin package from them.<br />

Harness `binaries` are not mirrored and still download. [Outbound connections](https://docs.oz0.ai/concepts/outbound-connections) lists every host a cluster may reach, and how to turn each off; nothing phones home.
- For [sandbox tier 1](https://docs.oz0.ai/concepts/security/sandbox-tiers#sandboxes), 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](https://docs.oz0.ai/fleet/sandbox-on-macos#what-is-tested-where)). 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](https://docs.oz0.ai/getting-started/install/linux-sandbox#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](https://docs.oz0.ai/fleet/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](https://docs.oz0.ai/reference/ports).

For trying things out, dev mode needs none of this: one process on SQLite. See [Dev mode](https://docs.oz0.ai/fleet/dev-mode).

## Next

- [Quickstart](https://docs.oz0.ai/getting-started/quickstart): an agent running on your machine.
- [Run a cluster](https://docs.oz0.ai/fleet/cluster): servers on PostgreSQL.
- [Join nodes](https://docs.oz0.ai/fleet/join-nodes): machines in the fleet.
- [Install on Kubernetes](https://docs.oz0.ai/fleet/kubernetes): the container images and the Helm chart.
- [Docker](https://docs.oz0.ai/fleet/docker): the quickstart container, and compose for a small team.

## Previous section links

- <span id="sandbox-tier-1-on-linux">

sandbox-tier-1-on-linux

</span>

: [open this section](https://docs.oz0.ai/getting-started/install/linux-sandbox#sandbox-tier-1-on-linux).


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.
