Learn About

Deep workflow guides aligned to this documentation section.

Opta Accounts Masterclass

Account-control strategy, token posture, and multi-surface auth flows.

Auth

Opta account authentication supports password-based sign-in and browser OAuth. Successful login writes a local session file used by CLI account and sync commands.

Auth Modes

Password mode - opta account login --identifier ...
System browser OAuth - opta account login --oauth
Opta browser OAuth - opta account login --oauth-opta-browser

opta account signup creates a new account, then persists the issued session when available.

Environment Configuration

CLI auth requires a Supabase project URL and anon key. These can be set directly in environment variables.

Supabase auth config

export OPTA_SUPABASE_URL="https://<project>.supabase.co"
export OPTA_SUPABASE_ANON_KEY="<anon-key>"

# Fallback names also supported by the CLI:
export NEXT_PUBLIC_SUPABASE_URL="$OPTA_SUPABASE_URL"
export NEXT_PUBLIC_SUPABASE_ANON_KEY="$OPTA_SUPABASE_ANON_KEY"

Config discovery

If env vars are not set, the CLI attempts discovery from project-local .env.local files (for Accounts and Local Web workspaces).

Password Auth

Create account using email/password flow

opta account signup --identifier "matthew@optamize.biz" --name "Matthew Byrden"

opta account login --identifier "matthew@optamize.biz"

Inspect authenticated user, project, and session expiry

opta account status --json

Browser OAuth

Open system browser OAuth sign-in with 5-minute callback timeout

opta account login --oauth --timeout 300

Run OAuth inside an Opta-managed browser session

opta account login --oauth-opta-browser --oauth-cookie-jar default --timeout 300

After callback, deep-link back into another app

opta account login --oauth --return-to opta-init://auth/callback --json

OAuth timeout constraints

--timeout must be between 30 and 1800 seconds. Outside this range, login fails before browser launch.

Callback Security

OAuth callback relay is restricted to 127.0.0.1:<port> and guarded by a state token. The Accounts callback route rejects invalid or missing state.

CLI callback example

GET https://accounts.optalocal.com/cli/callback?port=58321&state=7d2f...
-> 302 http://127.0.0.1:58321/callback?access_token=...&refresh_token=...&state=7d2f...

The CLI verifies callback state before saving tokens. State mismatch results in login failure and no local session update.

Session Storage

On success, auth state is written to ~/.config/opta/account.json, with user profile, project ref, access token, refresh token, and expiry metadata.

Status payload fields

{
  "authenticated": true,
  "project": "cytjsmezydytbmjrolyz",
  "user": { "id": "...", "email": "...", "phone": null, "name": "..." },
  "session": { "tokenType": "bearer", "expiresAt": "2026-03-04T10:24:12.000Z" }
}

Logout

Clear local account state and attempt remote Supabase session revoke

opta account logout

Verify the CLI reports not logged in

opta account status

If Supabase env vars are unavailable during logout, local state is still cleared and a warning is printed for remote revoke.

When opta chat can't reach LMX (host down, invalid admin key, or LAN fallback failure) the Ink UI now boots with an Offline banner. The composer is disabled, the attempted hosts are listed, and a CTA points you at recovery commands instead of crashing the CLI.

What the notice means

The banner renders after provider probes fail and detectLocalAdminKey cannot authorize against any loopback or fallback host. It is safe to keep the CLI open—the UI stays read-only until you rerun diagnostics or fix the server.

Use these commands (in order) to clear the banner, re-run detection, and confirm the admin key:

Print discovery info, host/fallback list, and whether the admin key was auto-detected or overridden.

opta status

Slash command inside the chat UI that re-probes the current host/fallback set without restarting the CLI.

/server status

Calls the secured /admin/model endpoints; success confirms the admin key is accepted again.

opta models --json

Clears a stale override so the CLI falls back to the auto-detected loopback key.

opta config delete connection.adminKey

Admin Key Detection

Loopback hosts (e.g., 127.0.0.1, ::1) now trigger detectLocalAdminKey. After environment, project, and CLI overrides finish, the helper looks for server.admin_key inside ~/.opta-lmx/config.yaml, copies it into connection.adminKey, and pre-populates connection.adminKeysByHost for every loopback fallback host. Remote hosts never receive this key—changing connection.host to a non-loopback value forces the helper to restart detection so nothing leaks.

Check the source of truth

The CTA in the banner links to ~/.opta-lmx/config.yaml. Ensure server.admin_key is set there (or export OPTA_LMX_ADMIN_KEY) so automatic detection continues to work after reboots.

Manual overrides are still available:

Pin specific loopback hosts when multiple simulators are running.

opta config set connection.adminKeysByHost '{"127.0.0.1":"<key>"}'

Override detection globally. Remember to delete it after switching back to auto mode.

opta config set connection.adminKey <key>

Desktop Accounts Button

Opta Desktop apps (Code + Init) now ship an Accounts button in the header grid. Clicking it launches the system browser, renders the standard accounts.optalocal.com OAuth screen, then closes the tab after sign-in when the opta-code://auth/callback deep-link fires. The deep-link handler refreshes account state inside the app and the status badge flips to “Signed in” without requiring a manual reload.

If login looks stuck

Ensure macOS still allows opta-code:// deep-links (System Settings → Privacy & Security → Open URLs with Opta Code).
Run opta account status or opta account login --oauth from the CLI to confirm Supabase credentials while keeping the desktop app open.
Re-trigger the Accounts button after clearing blocked pop-ups or network proxies; the handler unsubscribes/subscribe automatically so repeated attempts are safe.

Successful desktop logins immediately unlock the CLI as soon as the daemon picks up the refreshed session file, so you can bounce between desktop and terminal without repeating the flow.

Overview

Sync