Split Oore across Macs

Use split roles when one Mac cannot provide every required service.

The guided v0.1.42 lifecycle supports macOS only. To run the Web node on a Linux host, see Run a Web node on Linux.

Supported compositions

What you need

• A supported Mac for each guided profile.
• A protected network path between each remote profile and the control plane.
• HTTPS for a remote control-plane URL, unless a separate private network protects HTTP.
• An Owner or Admin Oore API token for each Runner.
• Protected browser ingress for a browser-facing Web node.
• A single-use pairing code for a Trusted Proxy Web node.

1. Prepare the control plane

On the control-plane Mac, install the CLI and select the Control plane profile:

curl -fsSL https://oore.build/install | bash
~/.oore/bin/oore install --profile control-plane

Complete terminal setup before you add another profile. The control plane must report that setup is ready.

Use Identity provider or Trusted proxy access for a non-loopback browser route. Local Only access remains loopback-only.

2. Connect a browser client

Use a Web node only when the product web proxy must run on another Mac.

The control plane must use Identity provider or Trusted Proxy access. A Web node cannot sign in to a Local Only control plane.

For Trusted Proxy access, create a pairing code on the control-plane Mac:

oore frontend invite

Then install the Web node profile on the browser-ingress Mac:

curl -fsSL https://oore.build/install | bash
~/.oore/bin/oore install --profile web-node

Supply the ready control-plane URL. For Trusted Proxy access, also supply the new pairing code.

Keep the Oore web listener on loopback. Terminate TLS at the protected ingress on the same Mac.

The pairing code is single-use and expires. Create a new code after an expired or consumed attempt.

You can instead connect the hosted UI or a self-hosted static UI.

The Control plane profile has no local web service. Connect one browser client before you create tokens for other Macs.

3. Add a Runner

On each build Mac, install the Runner profile:

curl -fsSL https://oore.build/install | bash
~/.oore/bin/oore install --profile runner

Use the connected browser client to sign in to Oore. Open Settings > API tokens and create an Owner or Admin token.

Copy the token when Oore shows it. Supply that token and the ready control-plane URL during Runner setup.

Oore registers the Runner and starts its macOS service.

Install Git and each required platform tool on the Runner Mac. Missing build tools do not block Runner setup.

4. Add a CLI only operator

Install the CLI only profile on another operator Mac:

curl -fsSL https://oore.build/install | bash
~/.oore/bin/oore install --profile cli-only

Supply the ready control-plane URL. For a non-loopback control plane, use the connected browser client to create a token under Settings > API tokens.

Supply that token during setup.

Verify the composition

On each Mac, run:

oore status --daemon-url https://oore.example.com

Open the protected browser URL. Make sure that Settings > Runners shows each expected Runner as online.

Run a small build from an approved repository. Make sure that a remote Runner claims the build.

Keep live updates streaming through proxies

The browser receives build, release, and runner changes over a long-lived server-sent events (SSE) connection to GET /v1/events. Build logs use the same transport at /v1/builds/<build-id>/logs/stream. When a hop cuts or buffers these connections, the UI falls back to polling, so pages still work, but they update more slowly and send more requests.

Oore sends a keepalive comment every 15 seconds and marks each stream Cache-Control: no-cache, no-transform and X-Accel-Buffering: no. The Web node lifts its own idle timeout for these requests. Check every other hop between the browser and the control plane, such as HAProxy, Warpgate, or a load balancer:

• Idle timeouts. Each hop must allow at least 20 seconds without data. Use 60 seconds or more for headroom.
• Response buffering. Each hop must forward response bytes as they arrive. Don’t buffer or compress text/event-stream responses.
• Connection limits. Each open browser tab holds one events connection, plus one log connection while it shows a running build. Size connection limits for that.

For HAProxy, set the timeouts on the frontend and backend that carry /v1/ traffic:

defaults
  mode http
  timeout client  60s
  timeout server  60s
  timeout tunnel  1h

HAProxy streams response bodies without buffering by default. timeout client and timeout server govern an SSE response, and the keepalives reset them. timeout tunnel covers HAProxy configurations that switch a long response into tunnel mode. If you enable compression, HAProxy skips responses marked no-transform, so no change is needed. Don’t add http-response rules that wait for the full body.

To confirm the whole path, sign in through the browser entry point and open the developer tools. In the network panel, find the events request. It should show a ready event, stay open for several minutes, and show new events when a build changes state. If it closes at a fixed interval, find the hop with that idle timeout.

With an API token, you can test the same path from a terminal:

curl -N -H "Authorization: Bearer <token>" https://oore.example.com/v1/events

curl should print an event: ready line, then a : keepalive line every 15 seconds.

Troubleshooting

If remote setup fails, make sure that the control plane is ready and reachable through the protected path.

If Web node pairing fails, create a new pairing code. Then repeat oore setup on the Web node.

If Runner registration fails, create a current Owner or Admin token under Settings > API tokens.

Next step

Configure External Access for the browser entry point. Then monitor every role.