`oore setup`

After oore install, run oore setup. The command reads the installed profile and shows a plan first.

oore setup [OPTIONS] [COMMAND]

Use --plan to stop after the plan. It changes no files, services, or setup state.

Automatic interface

The default interface is auto.

Use --interface terminal or --interface browser to override this choice.

Browser setup requires the Complete profile. It supports this-device and identity-provider access.

Trusted Proxy setup uses the terminal. Over SSH, the automatic interface is the terminal.

The guided browser token is single-use and expires after 30 minutes.

Role journeys

Control plane setup uses the terminal. Browser setup is available only for Complete.

In this release, the Complete profile always binds its web service to loopback. The browser transport assertion does not change this rule.

Use a Web node behind protected ingress when its web listener must use a non-loopback address.

A Web node needs a control plane with Identity provider or Trusted Proxy access. Local Only works with the loopback Web UI in Complete.

Remote profiles need these values:

For a remote Runner or CLI, create an API token on the ready control plane:

1. Sign in to the Oore web UI.
2. Open Settings > API tokens.
3. Create a token and copy it when Oore shows it.

The Control plane profile has no local web service. Connect a Web node, hosted UI, or self-hosted client first.

Use an Owner or Admin token for Runner registration. These roles include Runner write access.

Pass the token through OORE_SESSION_TOKEN. For a private setup file, use runner_token_file or session_token_file.

Access choices

Complete and Control plane setup accept these access values:

Without an explicit value, interactive setup explains each choice. This device is the default.

Identity provider setup needs an interactive terminal or Complete browser setup. A file does not replace the first owner login.

Local Only sign-in is passwordless. The backend accepts it only over loopback, including a local SSH tunnel.

An unfinished idp_configured state has no owner. Terminal setup can replace it with This device or Trusted proxy access.

Setup never replaces an owner_created or ready access choice. Use Oore Settings after setup is ready.

Terminal OIDC callback

Terminal OIDC setup uses this stable callback URL:

http://localhost:4174/auth/callback

Add this exact URL to the identity provider before setup. Keep it registered for setup retries.

Over SSH, Oore prints an exact tunnel command for port 4174. Keep that tunnel open during owner sign-in.

Trusted Proxy proofs

Trusted Proxy uses terminal setup. For a Complete profile, Oore generates the internal proof between oore-web and the control plane.

Oore also generates an upstream proof when no override file exists. It stores the proof privately and prints its path.

Configure the access proxy to send the proof in this header:

x-oore-web-trusted-proxy-secret

The proxy must also send the signed-in email in the identity header selected during setup.

For a Control plane profile, the access proxy connects directly to oored.

When no override file exists, Oore stores the generated direct proof here:

<install-root>/secrets/control-plane-proxy-proof

Oore prints the exact proof header, selected email header, and a safe command that reads the proof file.

The direct proxy proof header is:

x-oore-trusted-proxy-secret

Main options

Transport options are assertions. They do not create encryption.

Use --backend-transport-protected with a concrete private IP when a private overlay network protects the control-plane listener. Oore also starts a loopback listener on the same port for its local CLI and runner.

Configuration files

The file can use YAML or JSON. Unknown fields cause an error.

Oore accepts only a private, current-user-owned regular file smaller than 1 MiB. Set its mode to 0600 or stricter.

This example prepares a local Complete or Control plane profile:

interface: terminal
access: this-device
owner_email: [email protected]
daemon_listen: 127.0.0.1:8787
web_listen: 127.0.0.1:4173

This example prepares a headless Runner:

interface: terminal
backend_url: https://oore.example.com
runner_name: mac-builder-1
runner_token_file: ./runner-token

This example prepares Trusted Proxy access:

interface: terminal
access: trusted-proxy
owner_email: [email protected]
trusted_proxy:
  user_email_header: x-auth-request-email
  trusted_proxy_cidrs:
    - 127.0.0.1/32

Supported top-level keys are:

interface
access
owner_email
state_file
daemon_url
daemon_listen
web_listen
backend_url
runner_name
runner_token_file
session_token_file
pairing_code
browser_transport_protected
backend_transport_protected
trusted_proxy

The trusted_proxy object accepts these keys:

user_email_header
trusted_proxy_cidrs
shared_secret_file
upstream_shared_secret_file

Relative state and secret paths resolve from the configuration file directory.

Secret files must be regular files owned by the current user. Their mode must be 0600 or stricter.

Trusted Proxy proof files are optional overrides. If you supply them, the two files have different roles:

• shared_secret_file supplies the proof for the hop that reaches the control plane.
• upstream_shared_secret_file proves the external access proxy to oore-web.

If you omit a file, Oore generates that proof. Never reuse one proof across both hops.

Control plane profiles do not need the upstream file because they do not run oore-web.

For Control plane, Oore keeps a generated direct proof under the install root. A supplied shared_secret_file stays in its original location.

Explicit CLI values override file values. Environment variables supply only their documented CLI options.

Boolean CLI flags can only add true. Omit a flag to use its file value.

Review and apply a file with these commands:

oore setup --config ./oore-setup.yaml --plan
sudo -v
oore setup --config ./oore-setup.yaml

Administrator access

Complete, Control plane, Runner, and Web node setup manage macOS services.

In an interactive terminal, Oore requests administrator access after the plan. The request expires after 60 seconds.

Without an interactive terminal, Oore uses sudo -n -v. It never opens a password prompt.

For headless service setup, run sudo -v before oore setup.

If authorization fails, Oore stops before it changes setup state.

CLI only setup does not request administrator access.

Complete profile result

For This device and Identity provider access, Complete setup prints the local web URL.

Over SSH, it also prints the exact tunnel command. Run that command on your computer and keep it open before you open the URL.

For Trusted Proxy access, Complete setup does not print the loopback URL. It tells you to finish and open the proxy’s HTTPS address.

Environment variables

Legacy direct commands

Existing automation can still use these commands:

oore setup init --mode <local|trusted-proxy> [OPTIONS]
oore setup token [--ttl <DURATION>] [--state-file <PATH>] [--json]

The legacy token lifetime defaults to 15 minutes.

Use the main oore setup journey for new installations.

See Configure External Access and Setup states for related contracts.