Troubleshooting & FAQ

Installing and launching

macOS won't open the app the first time. The Direct build is notarized but downloaded outside the App Store, so macOS asks you to confirm on first launch. Open it once and the prompt won't return. If macOS blocks it entirely, make sure you copied Ringmaster into Applications and opened it from there, not from the disk image.

Is my Mac supported? You need macOS 14 (Sonoma) or later on Apple silicon. Older macOS versions aren't supported.

Licensing

Sign-in asks for a code. Your account has two-factor authentication enabled. Enter the six-digit code from your authenticator. Your password is never stored on the device, only used to sign in.

"Activation limit reached." The license is activated on as many Macs as it allows. Free a seat with Settings → License → Deactivate This Mac… on a machine you no longer use, then activate this one. If you can't reach the other machine, contact support.

Status says "Licensed (offline)." Ringmaster couldn't reach the licensing server recently, so it's running on the cached token inside its grace window. This is normal on a plane or behind a strict network. It'll refresh on its own once you're back online; you can also press Refresh in Settings → License.

A feature is locked. Multi-agent modes (parallel, race, consensus, specialist), advanced metrics, and report export require a license. Single-agent runs, validation, review, and replay are always available. Open Settings → License to activate this Mac. See what a license unlocks.

Running workflows

A runtime shows as unavailable. Open Settings → Runtimes; it shows each runtime's status and what to do. A CLI agent needs its command on your PATH; a local server (LM Studio, Ollama, vLLM, llama.cpp) needs to be running with a model loaded; a hosted API needs its key set. The panel spells out the exact fix for each one. See Providers & runtimes.

"No models loaded" on a local server. The server is running but has nothing to serve. In LM Studio, load a model from the Developer tab; with Ollama, ollama pull <model>; for vLLM and llama.cpp, the model is the one you passed when you started the server. Reselect the runtime afterward.

A run stops and won't continue. That's usually a review gate doing its job: a stage finished and is waiting for you to approve, revise, or reject. Open the stage and make a decision. A stage can also stop because a blocking validator failed; the validation results show what didn't pass. See Running workflows and Validation.

A downstream stage is blocked. It consumes a stage you haven't approved yet. Approve the upstream stage and the downstream one unblocks. If you un-approved something, anything that depended on it goes back to blocked by design.

A bundled prompt shows problems in the Prompt Library. Built-in workflow files are seeded into your workspace once and never overwritten afterward, so your edits always survive updates. The flip side: when an app update fixes a bundled prompt, a workspace that already has the old copy keeps it. If the Prompt Library badges a built-in prompt (for example an output name that doesn't match [A-Za-z_][A-Za-z0-9_]*), delete that file from your workspace's prompts/ folder — Reveal in Finder in the library takes you straight to it — then relaunch the app. The seeder restores the current version. Your own prompts and any bundled files you've edited are never touched.

The CLI

ringmaster run exits with a non-zero code. The codes are deliberate. 1 is a usage error and 2 is a validation failure. 3 means it stopped cleanly at a review gate; open the run in the app to finish it. 4 is a policy refusal (pass --acknowledge-policy if appropriate). 5 means a gated mode without a license. 6 means a provider is unavailable or a credential is missing; the message names what it wanted. The full table is in The ringmaster CLI.

The CLI can't find my API key. A headless run reads keys from the environment, not the Keychain. Set the provider's variable in the shell or CI environment, for example GEMINI_API_KEY or OPENROUTER_API_KEY (or the RINGMASTER_-prefixed form). See Credentials in CI.

"This run is in use." The app or another CLI process has the run open. Ringmaster allows one writer per run so nothing gets corrupted. Close it in the app, or wait for the other process to finish, then retry.

Finding your data

Runs and artifacts live in each workspace's .ring/runs/ directory. The cached license token, app metadata, and custom-endpoint profiles are in ~/Library/Application Support/Ringmaster/. API keys are in your macOS Keychain. Deleting a run from the app moves it to the Trash, so a mistaken delete is recoverable.

Getting help

When something fails against the licensing or update service, the error includes a copyable request ID. Include it when you contact support; it lets us find the exact request in the logs. The support inbox is hello@luna-tech.co.