Set Up Your Instance

This tutorial walks you through the Oore CI setup wizard, from starting the daemon to a configured instance. Setup state lives in oored; the CLI, hosted UI, and self-hosted UI are just clients for the same backend setup API.

During setup you choose one access mode:

Mode	What it means	Requirements
Local Only	Loopback-only local login for one-machine evaluation or operator access.	Browser or CLI reaches the backend on loopback. No local passwords.
Remote OIDC	Non-loopback users authenticate with any OIDC-compatible identity provider.	HTTPS browser path to the backend and OIDC issuer/client details.
Remote Trusted Proxy	An upstream identity-aware proxy authenticates users and forwards identity headers to Oore.	HTTPS browser path through that proxy, a trusted identity header, and a shared secret on proxy-to-backend hops.

What you need

• Oore CI installed
• For Remote OIDC: your issuer URL, client ID, and client secret if required by your provider
• For Remote Trusted Proxy: the forwarded user email header, trusted proxy peer CIDRs, and a shared secret from the proxy path to the daemon
• For hosted UI setup: an HTTPS backend URL reachable from your browser network path

1. Start the daemon

Open a terminal and start oored:

oored run --listen 127.0.0.1:8787

You should see:

INFO oored: using database path="/Users/you/Library/Application Support/oore/oore.db"
INFO oored: database ready instance_id="..." state=BootstrapPending
INFO oored: encryption key ready
INFO oored: starting oored daemon listen=127.0.0.1:8787

Leave this terminal running. The daemon listens on 127.0.0.1:8787 by default.

TIP

Override the listen address with --listen or the OORED_LISTEN_ADDR environment variable.

2. Generate a bootstrap token

In a second terminal, generate a one-time bootstrap token:

oore setup token --ttl 15m

This runs oore setup token --ttl 15m and outputs:

Bootstrap token generated.

Token:   a1b2c3d4e5f6...
Expires: 2026-02-06 14:30:00 (15m from now)
State:   bootstrap_pending
DB:      /Users/you/Library/Application Support/oore/oore.db

To complete setup, either:
  1. Run: oore setup
  2. Open a web UI that can reach this backend, add the instance, then continue setup

Copy the token value. You'll need it in the next step.

WARNING

The bootstrap token is single-use and expires after its TTL (default: 15 minutes). If it expires, run oore setup token --ttl 15m again.

3. Complete setup

Choose one of two clients: the web UI or the interactive CLI. Both configure the same backend daemon.

Option A: Web UI

1. Open the UI that can reach your backend:

   • ci.oore.build for HTTPS-reachable backends.
   • http://127.0.0.1:4173 for the bundled local frontend.
   • your split frontend origin if oore-web is running on a separate host.

2. Add your backend instance:

   • Hosted UI: enter the HTTPS backend URL.
   • Local or split frontend proxy: leave Backend URL empty so requests use the same origin proxy.

3. Open the setup flow for that instance.

4. Follow the setup steps:

   Step	What you do
   1. Bootstrap	Paste your bootstrap token to authenticate
   2. Mode	Choose Local Only, Remote OIDC, or Remote Trusted Proxy
   3. Auth setup	Configure OIDC, or trusted-proxy header settings, or skip directly to owner in local mode
   4. Owner	Verify the owner account through OIDC, trusted proxy, or local owner creation
   5. Finalize	Confirm to lock setup endpoints permanently

Hosted UI reachability

ci.oore.build is frontend-only. It does not host your daemon and it cannot call http://127.0.0.1:*. Use CLI setup or the local frontend for loopback-only setup, or expose the backend through HTTPS before using the hosted UI.

Option B: Interactive CLI

Run the setup command:

oore setup

The CLI walks through the same backend setup flow. This example shows Remote OIDC; Local Only skips provider configuration, and Remote Trusted Proxy asks for proxy identity settings instead.

oore setup -- interactive instance configuration

Connected to oored at http://127.0.0.1:8787
Instance:  a1b2c3d4-...
State:     bootstrap_pending

[Step 1/5] Bootstrap token verification
  Generating bootstrap token (TTL: 15m)...
  Verifying token with daemon...
  > Bootstrap verified. Session token acquired.

[Step 2/5] Access mode
  Mode: Remote OIDC
  > Access mode saved.

[Step 3/5] OIDC provider configuration
  OIDC Issuer URL: https://accounts.google.com
  Client ID: your-client-id.apps.googleusercontent.com
  Client Secret (optional, press Enter to skip): ****
  > OIDC provider configured.

[Step 4/5] Owner account setup
  Continue with OIDC authentication? [y/N] y
  Waiting for authentication callback...
  > Owner verified: admin@example.com

[Step 5/5] Finalize setup
  Complete setup? This will lock all setup endpoints. [y/N] y
  > Setup complete! Instance ID: a1b2c3d4-...

If you choose Remote Trusted Proxy, setup asks for:

• initial owner email
• proxy preset (Generic proxy, Warpgate, or Custom header)
• trusted user email header (Generic proxy uses x-oore-user-email; Warpgate uses x-warpgate-username)
• optional trusted proxy CIDRs
• shared secret sent by the trusted proxy path as x-oore-trusted-proxy-secret

Then the owner is claimed from the trusted proxy-authenticated request instead of an OIDC redirect. The proxied email must match the configured initial owner email, so setup cannot accidentally create the wrong first owner. Provider-specific guides, such as Warpgate examples, are examples of this generic mode rather than separate setup modes.

If the browser reaches the backend through oore-web, do not forward browser-supplied identity headers directly. Configure the auth proxy in front of oore-web to send the identity header plus x-oore-web-trusted-proxy-secret; oore-web strips identity headers unless that upstream proof is present, then injects the backend shared secret when proxying /v1/*.

INFO

The CLI OIDC flow opens your default browser and listens on a random local port for the callback. Make sure your OIDC provider's allowed callback URLs include http://localhost:* or the specific port shown in the CLI output.

4. Verify

Confirm the instance is in ready state:

curl http://127.0.0.1:8787/v1/public/setup-status

Expected response:

{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "ready",
  "setup_mode": false,
  "is_configured": true
}

Once state is ready, setup endpoints are permanently disabled and the instance is ready for normal use.

DANGER

Finalizing setup is irreversible. All setup endpoints (/v1/setup/*) are permanently disabled after this step.

What happens during setup

The instance progresses through four states. Each step requires the previous one to complete:

bootstrap_pending → idp_configured → owner_created → ready

State	What happened	What's next
bootstrap_pending	Daemon started, waiting for bootstrap token	Verify token to get a setup session
idp_configured	Access-mode preferences and any remote auth details have been configured	Verify or claim the owner account
owner_created	Owner identity verified, account created	Finalize to lock setup
ready	Setup complete, all setup endpoints disabled	Instance ready for normal use

For the full state machine reference, see Setup States.

Troubleshooting

"Cannot reach daemon"

Make sure oored is running. Start it with:

oored run --listen 127.0.0.1:8787

"Setup already complete"

The instance has already been configured. Check with:

curl http://127.0.0.1:8787/v1/public/setup-status

"OIDC discovery failed"

The daemon couldn't fetch the OpenID Connect discovery document from your issuer URL. Verify that:

• The issuer URL is correct (e.g., https://accounts.google.com, not https://accounts.google.com/)
• The issuer supports /.well-known/openid-configuration
• The daemon has internet access

"Session expired"

Setup sessions expire after 30 minutes of inactivity. Restart the setup process from step 2.

Next steps

Your instance is running and authenticated. Continue with:

• Configure OIDC — detailed provider setup guides for Remote OIDC
• Split Backend and Frontend — generic multi-host deployment shape
• Mac Studio + NetBird + Warpgate — one internal-only Trusted Proxy deployment example
• API Reference — explore the API
• CLI Reference — all available commands