Ringmaster runs AI-assisted work as a structured pipeline instead of a chat. You define a workflow, run its stages across the agents you choose, review what comes back, and keep a complete record of how each result was produced. This guide takes you from a fresh install to your first reviewed artifact in a few minutes.

Before you start

You'll need a Mac running macOS 14 (Sonoma) or later on Apple silicon, and at least one way to run a model. The fastest way to try Ringmaster with zero setup is a local model server like LM Studio or Ollama: nothing to configure, no API key, and your prompts never leave the machine. If you'd rather use a CLI agent you already have installed (Claude Code, Codex, Copilot, Gemini, Kiro), that works too. See Providers & runtimes for the full list.

1. Install and launch

Download the latest signed build from your portal at ringmaster.luna-tech.co, open the disk image, and drag Ringmaster to your Applications folder. The first time you open it, macOS will ask you to confirm; that's expected for a notarized app downloaded outside the App Store. Full detail is in Installation & licensing.

2. Activate your license

The first time you open Ringmaster on a Mac that isn't licensed yet, it offers to activate right from the launcher: an Activate Ringmaster panel opens on its own, and a banner with Sign In & Activate stays on the launcher until this Mac is licensed. You can also reach the same flow any time from Settings → License.

Sign in with the email and password for your account; if you have two-factor turned on, you'll be asked for a code. Your password is never stored on the device. Once you're signed in, you'll see the licenses on your account. Click Activate This Device on the one you want to use here. That's it. Ringmaster caches a signed license token locally, so it keeps working offline and doesn't phone home on every launch.

You don't strictly need a license to follow this guide. Single-agent runs, validation, review, and replay are always available. A license unlocks the multi-agent modes (parallel, race, consensus, specialist), advanced metrics, and report export.

3. Open a workspace

A workspace is just a folder on your Mac, usually a project or repository you're working in. Ringmaster stores its runs and history inside that folder, in a .ring directory, so everything stays next to the work it describes.

Choose File → Open Workspace… and pick a folder. A scratch directory is fine for now. Your workspace opens on a Default project that holds all its runs; later, when you have several lines of work going at once, you can add more projects to keep their run histories separate (see Projects).

4. Run your first stage

Ringmaster ships with thirteen built-in workflows, ordered in the Workflows list from simplest to most advanced — from Single Prompt at the top, through everyday drivers like Code Review and Plan & Implement, up to multi-agent showcases like Consensus Review and Race Answer. Start with the first one: Single Prompt is one stage, works with any runtime, and shows the whole run–review loop in miniature. Pick it and click New Run. A workflow is made of stages; each stage sends a prompt to a runtime and collects whatever files it produces.

Select the first stage and choose its runtime; if you started LM Studio or Ollama, pick that. Run the stage (⌘R). Output streams in live in the Runtime Output drawer, and when it finishes you get an attempt: one complete execution of that stage, numbered and kept on disk.

Not happy with the result? Run it again. Each run is a new attempt; nothing is overwritten, and you can compare them later.

5. Review and promote

Most stages pause at a review gate when they finish; Ringmaster doesn't advance on your behalf at the points that matter. Read the attempt, and when one is good, approve and promote it. Promotion marks that attempt's output as the canonical artifact for the stage, which is what any downstream stage will consume.

That human checkpoint is the whole point: the model generates, you decide.

6. Find your artifact

Promoted artifacts live in the Artifacts browser, and on disk under your workspace's .ring/runs/ directory. Every artifact carries its full provenance: which workflow version, which runtime and model, the exact prompt, the inputs it consumed, and your review decision. You can open Show Provenance on any artifact to see all of it, or export a report (see Provenance, reports & metrics).

Where to next

• Core concepts: the handful of terms the rest of the docs lean on.
• Projects: keep separate streams of work in one workspace.
• Authoring workflows: write your own workflow YAML.
• Multi-agent execution: run a stage across several models and compare.
• The ringmaster CLI: run the same workflows headlessly in CI.

Ringmaster has a small vocabulary. Once these terms click, the rest of the product (and the rest of these docs) reads easily. Here they are, roughly in the order you meet them.

Workspace

A workspace is a folder on your Mac, usually a project or repository. When you point Ringmaster at a folder, it keeps everything it produces inside a .ring directory there: run history, artifacts, events, and metadata. Your work and the record of how it was made stay together, and you can have several workspaces open at once.

Project

A project is a stream of work inside a workspace. One workspace often carries several at once — a feature, a bug fix, an experiment — and a project keeps each one's runs separate and pins the short list of workflows it actually uses. Every workspace has a Default project that holds anything you haven't filed elsewhere (including runs from before you made any projects), and one project is active per window, scoping its Recent Runs, Search, and the runs you start. See Projects.

Workflow

A workflow is a repeatable process, written as a YAML file. It describes a sequence of stages that turn an idea into specs, plans, implementations, reviews, tests, whatever the process calls for. Because it's a plain file in your repo, a workflow versions alongside your code and travels with the project. Ringmaster ships thirteen built-in workflows, ordered simplest to most advanced; you can also write your own (see Authoring workflows).

Stage

A stage is the atomic unit of work: one prompt, one runtime invocation, one set of output files. Stages run in order, and a stage can consume the output of earlier stages, so a later stage sees what came before. A stage declares which runtime runs it, which model (optionally), what it consumes, what to validate, and whether it needs review.

Prompt

A prompt is the Markdown file a stage sends to its runtime, referenced by path from the workflow. A prompt named *.pml.md can carry YAML front matter declaring its inputs (with descriptions and defaults, filled into {{inputs.<name>}} placeholders) and outputs — self-documentation that the Prompt Library renders so you can browse every prompt in the workspace, see what it takes and produces, and spot broken ones before a run. See Prompt Library.

Run

A run is one execution of a workflow from start to finish. Each run gets its own directory under .ring/runs/, identified uniquely, holding every stage, attempt, and artifact it produced. Your recent runs are listed in the app so you can return to any of them.

Attempt

An attempt is one execution of a single stage within a run, numbered 001, 002, and so on. Re-running a stage never overwrites; it creates the next attempt. That's what lets you try a stage several times, compare the results, and pick the one you want without losing the others.

Execution and slot

Most of the time an attempt is one execution. But when a stage runs in a multi-agent mode, a single attempt contains several executions running side by side, one per agent. Each execution gets its own slot (a directory named like 001-claude-code, or the role name in specialist mode) so their outputs never mix. See Multi-agent execution.

Artifact

An artifact is a file a stage produces: specification.md, plan.md, output.json, anything. Each execution writes its artifacts into its own directory; nothing merges on its own. When you approve an attempt, its artifacts become canonical, the version downstream stages will consume.

Review gate and promotion

A review gate is the pause at the end of a stage where a human decides what happens next. You can approve an attempt, request a revision, or reject it. Approving an attempt promotes its artifacts to canonical. This is deliberate: Ringmaster won't carry unreviewed work downstream at the points you've marked as needing judgment. (A stage can opt out with review.required: false if you want it to auto-approve on a clean run.)

Validator

A validator is an automated check that runs against a stage's output: does the file exist, does this Markdown have the required sections, does this JSON match a schema. Each validator has a severity; a blocking failure prevents auto-approval, while lower severities just surface in the UI. Validators are how a stage refuses to pass malformed work downstream. See Validation.

Runtime

A runtime is the thing that actually runs a stage: a CLI agent (Claude Code, Codex, Copilot, Gemini, Kiro), a local model server (LM Studio, Ollama, vLLM, llama.cpp), or a hosted API (Gemini API, OpenRouter, or a custom OpenAI-/Anthropic-compatible endpoint). Workflows name runtimes by a short ID like claude-code or ollama. Because runtimes are interchangeable, you can swap one for another without touching the rest of the workflow. See Providers & runtimes.

Comparison and consensus

When several executions run in one attempt, Ringmaster builds a comparison, a side-by-side table of their status, validation results, timing, and token use. In consensus mode it adds a structural analysis on top: which sections every candidate agreed on, where they diverged, and how similar they are. The comparison is evidence for your review; Ringmaster never picks a winner for you. See Multi-agent execution.

Replay

Replay re-runs a recorded attempt, optionally against a different runtime or model, feeding it the exact original prompt and inputs. It's how you ask "what would a different model have done with the same task?" without rebuilding anything. See Replay.

Provenance

Provenance is the complete record behind an artifact: the workflow version, run, stage, and slot that produced it; the runtime and model; the prompt file; the inputs it consumed; the validation outcome; your review decision; and timestamps. Every artifact has it, and you can view or export it at any time. See Provenance, reports & metrics.

System requirements

• macOS 14 (Sonoma) or later
• Apple silicon (M-series)
• Around 2 GB of free disk space, plus whatever your local models need if you run them
• A network connection for hosted providers and for license activation, though once activated, Ringmaster runs offline

Editions

Ringmaster comes in two builds:

• Direct: signed with a Developer ID and notarized by Apple, downloaded from your portal. This build updates itself (see Updates).
• App Store: sandboxed and distributed through the Mac App Store, which handles its updates. It does not include the built-in updater.

The two are otherwise the same product. Most people running CLI agents and local model servers will want the Direct build.

Installing

1. Sign in to your portal at ringmaster.luna-tech.co and download the latest build. Downloads are tied to your licensed account; the portal mints a short-lived download link on demand.
2. Open the downloaded disk image and drag Ringmaster into your Applications folder.
3. Launch it. Because the Direct build is notarized but downloaded outside the App Store, macOS shows a one-time confirmation the first time you open it. Click Open.

If you want to confirm the download, the portal publishes a SHA-256 for each build; compare it against your file before opening.

Signing in and activating

The first time you launch Ringmaster on a Mac that isn't licensed, it offers to activate without your having to go looking: an Activate Ringmaster panel opens automatically, and a banner with Sign In & Activate remains on the launcher until this Mac is licensed. The same controls live in Settings → License, which is also where you manage your license afterward. The prompt is an invitation, not a wall: you can dismiss it with Maybe Later and still use single-agent runs, validation, review, and replay.

Wherever you start from, there are two parts to getting licensed: signing in to your account, and activating this Mac.

1. Sign in. Enter your account email and password. If your account has two-factor authentication enabled, you'll be prompted for a six-digit code. Your password is used only to sign in; it is never stored on the device.
2. Activate this device. Once signed in, the Your Licenses section lists the licenses on your account, each showing its tier and how many devices it's activated on (for example, 2 of 5 Macs). Click Activate This Device on the license you want to use here.

Ringmaster then caches a signed license token in ~/Library/Application Support/Ringmaster/. That token is what's checked at launch, so the app keeps working without a network connection and never blocks startup waiting on one.

What a license unlocks

Some capabilities are always available, with or without a license:

• Single-agent stage execution
• Validation
• Review gates and promotion
• Replay
• Searching your run history and finding similar runs
• Browsing your decision history
• Importing a workflow package

A license unlocks the rest:

• Multi-agent execution: parallel, race, consensus, and specialist modes
• Advanced metrics, cost trends, budgets, and the trust score
• Report export
• The eval harness (ringmaster eval and ringmaster dataset)
• Automated repair loops
• Exporting a workflow package
• Custom-script validators (Direct build only)

If you try to run a workflow that uses a gated mode without the entitlement, Ringmaster stops before running anything and tells you exactly what's needed, with a link to Settings → License. It never starts a run it can't finish.

License states

The License tab shows your current state at a glance:

• Licensed: token valid and recently refreshed.
• Licensed (offline): token valid, but Ringmaster hasn't been able to reach the server lately. It keeps working through a grace window defined in the token.
• Evaluation: a valid evaluation-tier license.
• Expired, Suspended, Invalid, Unlicensed: the gated features turn off; the rest of the app keeps working. The tab explains what to do, and surfaces a copyable request ID you can include if you contact support.

Moving to a new Mac

Activations are counted against your seat total. To free a seat, open Settings → License → Deactivate This Mac… on the machine you're leaving. That releases the activation slot so you can activate another device. If you hit your activation limit, deactivate a machine you no longer use, or contact support.

Where Ringmaster keeps things

• Application support: ~/Library/Application Support/Ringmaster/ holds the cached license token, app metadata, and custom-endpoint profiles.
• Keychain: API keys and credentials live in your macOS Keychain, never in plain files.
• Workspaces: run history and artifacts live in each workspace's own .ring directory, alongside the work they describe.

A workflow is a YAML file. It lists the stages to run, what each one does, and how they connect. Because it's a plain file, it lives in your repo and versions with your code. This page is the field-by-field reference; if you just want to see one end to end, jump to Worked examples.

The shape of a workflow

id: spec-and-plan
name: "Spec and Plan"
description: Turn a brief into a reviewed spec, then a plan.
defaultRuntime: claude-code
stages:
  - id: spec
    name: Write the specification
    prompt: prompts/spec.md
    validators:
      - type: markdown_sections
        artifact: specification.md
        required: [Overview, Requirements, Non-Goals]
  - id: plan
    name: Draft the plan
    prompt: prompts/plan.md
    consumes: [spec]

Top-level keys

Key	Required	Notes
id	yes	Workflow identifier. Lowercase letters, digits, and hyphens; 1–64 characters; starts and ends alphanumeric.
name	yes	Human-readable name shown in the app.
description	no	Longer description of what the workflow does.
defaultRuntime	no	A runtime ID used by any stage that doesn't name its own. Must be a registered runtime (see Providers & runtimes).
stages	yes	The list of stages, in order. At least one.

Stage keys

Key	Required	Notes
id	yes	Stage identifier, unique within the workflow. Same character rules as the workflow id.
name	yes	Human-readable stage name.
description	no	Longer description of the stage.
prompt	yes	Path to the prompt file, relative to the workflow file (or absolute). Must resolve inside the workspace.
runtime	conditional	Runtime ID for this stage. If omitted, Ringmaster falls back to defaultRuntime. One of the two must resolve to a registered runtime.
model	no	A model ID to pin for this stage (for example sonnet, or google/gemma-4-e4b). Left out, the runtime's default model is used.
consumes	no	Artifacts from earlier stages this stage should receive. See Connecting stages.
additionalInstructions	no	Extra text appended to the compiled prompt at run time.
review	no	The review gate. See Review.
validators	no	Automated checks on the output. See Validation.
execution	no	Multi-agent strategy. Absent means a single execution. See Multi-agent execution.
iteration	no	Loop a single-execution stage until it's approved. See Iteration.

A note on prompt: the value is a path to a file, not the prompt text itself. Keep your prompts as Markdown files next to the workflow. This keeps the workflow readable and lets prompts version on their own. Use additionalInstructions for short, stage-specific notes you'd rather keep inline.

Prompt files (PML)

A prompt can be any Markdown file. Name it *.pml.md and it gains an optional YAML front matter that declares its inputs and outputs — this is the format every built-in workflow uses, and it's what the Prompt Library renders as documentation:

---
inputs:
  - name: focus
    description: What this review should concentrate on.
    default: correctness and error handling
outputs:
  - name: review_md
    description: The review, tiered Blocker / Should-fix / Nit.
---

Review the changes with a focus on {{inputs.focus}}.
...

• Inputs become {{inputs.<name>}} placeholders in the body. At run time each placeholder is replaced with the input's default. An escaped \{{inputs.foo}} passes through literally.
• Outputs document what the prompt produces. They're informational today — good documentation for anyone (including the library view) reading the prompt.
• Input and output names must match [A-Za-z_][A-Za-z0-9_]* — letters, digits, and underscores, not hyphens. Duplicate names and placeholders that reference undeclared inputs are also errors.

A .pml.md file is parsed and validated when the stage runs; a problem fails the attempt with a message naming it. The Prompt Library shows the same problems ahead of time, so you don't have to discover them mid-run. Plain .md prompts skip all of this and are sent as-is.

Connecting stages

Stages run top to bottom. A later stage names earlier ones in consumes to receive their canonical (promoted) output:

stages:
  - id: research
    name: Research
    prompt: prompts/research.md
  - id: draft
    name: Draft
    prompt: prompts/draft.md
    consumes: [research]        # draft sees research's promoted output
  - id: review
    name: Review
    prompt: prompts/review.md
    consumes: [research, draft] # and this one sees both

A reference is just the earlier stage's id. You can also write stage-id.output explicitly; in this version output is the only logical name. References must point backward: a stage can't consume something that runs later, and Ringmaster will tell you at validation time if it does.

Only promoted artifacts flow downstream. If a stage has a review gate, the work it produces isn't visible to later stages until you approve it.

The review gate

By default every stage pauses for review when it finishes: you approve, request a revision, or reject, and approving promotes the output. To let a stage approve itself on a clean run, turn the gate off:

    review:
      required: false      # auto-approve if it succeeds and no blocking validator fails

With the gate off, a stage that succeeds and passes its blocking validators promotes automatically and the run continues. Anything less (a failure, or a blocking validation failure) still stops for you. (You may see the older autoApproveOnSuccess: true in existing workflows; it means the same thing as review.required: false.)

Iteration

A single-execution stage can loop until you approve it, carrying its previous attempt and your feedback into the next try:

    iteration:
      enabled: true
      mode: until-approved
      preserveContext: true     # include the prior attempt in the next prompt (default)

Iteration applies to single-execution stages only; it can't be combined with a multi-agent execution block.

Identifiers, briefly

Workflow IDs, stage IDs, and specialist role names all follow the same rule: lowercase letters, digits, and hyphens, 1–64 characters, starting and ending with a letter or digit. The name merged is reserved and can't be used as a role.

PML input and output names follow a different rule — [A-Za-z_][A-Za-z0-9_]*, underscores rather than hyphens — because they double as placeholder keys. Easy to trip over when you're used to the kebab-case IDs everywhere else.

Validate before you run

You don't have to run a workflow to find out whether it's well-formed. The CLI checks everything (schema, references, runtime IDs, validator config) and reports problems with line numbers:

ringmaster validate path/to/workflow.yaml

It exits 0 when the workflow is valid and 2 when it isn't, which makes it a natural first step in CI. See The ringmaster CLI.

Worked examples

A two-stage workflow

id: spec-and-plan
name: "Spec and Plan"
description: Turn a brief into a reviewed spec, then a plan that builds on it.
defaultRuntime: claude-code
stages:
  - id: spec
    name: Write the specification
    prompt: prompts/spec.md
    validators:
      - type: markdown_sections
        artifact: specification.md
        required: [Overview, Requirements, Assumptions, Non-Goals]
      - type: artifact_exists
        artifacts: [specification.md]
  - id: plan
    name: Draft the plan
    prompt: prompts/plan.md
    consumes: [spec]
    review:
      required: true

The first stage writes a spec and won't auto-pass unless specification.md exists and contains the four required sections. You review it, approve it, and the second stage (which consumes the spec) becomes runnable.

A stage that fans out across models

  - id: draft
    name: Draft (three models)
    prompt: prompts/draft.md
    execution:
      mode: parallel
      agents:
        - runtime: claude-code
          model: sonnet
        - runtime: openrouter
          model: anthropic/claude-opus-4.5
        - runtime: ollama

All three run the same prompt at once; you get a comparison and pick the one to promote. The mechanics of each mode (parallel, race, consensus, specialist) are in Multi-agent execution.

Running a workflow is a loop: run a stage, look at what came back, decide, move on. Ringmaster keeps every step on disk so you can always back up, try again, or compare.

Starting a run

Open a workspace, pick a workflow from the Workflows list, and start a new run. The run opens to its stages laid out in order. A fresh run has nothing executed yet: the first stage is ready, and stages that depend on others wait until their inputs exist.

The run is filed under the window's active project — the Default project, unless you've switched to another — which is also what scopes the Recent Runs list and Search.

Running a stage

Select a stage, confirm its runtime and model, and run it. Output streams in live in the Runtime Output drawer as the agent works. When it finishes you have an attempt: one numbered, recorded execution of that stage.

When a workflow doesn't pin a runtime, the picker defaults to whatever you last ran with — so once you've settled on a runtime, new stages and new runs follow it. A workflow that names a runtime or defaultRuntime is always honored, and the picker only offers runtimes that are actually available.

You can also swap the prompt for a single run: the Prompt File row's Browse… button picks any file, and the Library… menu offers every prompt in your workspace, grouped by workflow (see Prompt Library). The override applies to attempts you start from this form, and Revert takes you back to the workflow's own prompt.

If you don't like the result, run it again. Each run is a new attempt (002, 003, …) and the earlier ones stay put. Because nothing is overwritten, trying a stage a few times and keeping the best result is a normal part of working, not a copy-paste chore.

Stage states

A stage shows where it stands:

• Ready: its inputs exist and it can run.
• Running: an attempt is in progress.
• Waiting for review: an attempt finished and is waiting on your decision.
• Succeeded: an attempt was approved (or auto-approved); its output is canonical.
• Blocked: it depends on a stage that isn't approved yet.
• Failed: the last attempt failed or hit a blocking validation failure.
• Cancelled: the attempt was cancelled; whatever output existed is kept.

The review gate

When a stage finishes, it usually pauses for review instead of advancing on its own. The core decisions are:

• Approve and promote: accept the attempt. Its artifacts become canonical and any downstream stages unblock.
• Request a revision: send it back with feedback for another attempt. If the stage uses iteration, your feedback and the prior attempt carry into the next try.
• Reject: mark the attempt as not acceptable.

You can also re-run a stage, flag an attempt for follow-up, or promote an edited copy. Promotion is the moment work moves downstream: until you approve, later stages can't see a stage's output, which is what keeps unreviewed work from flowing through a pipeline.

Changing your mind

If you un-approve a stage after the fact, Ringmaster cascades the consequence: anything downstream that consumed it goes back to blocked, because its input just changed. You're never left with a later stage built on an input you've since pulled. Re-approve, or run a new attempt, and the chain comes back.

Cancelling

A run that's taking too long, or heading the wrong way, can be cancelled. In a single-agent stage that stops the one execution. In a multi-agent stage you can cancel one slot or the whole attempt; whatever output already exists is kept, marked cancelled, so you never lose the record of what happened. Cancellation reaches real subprocesses and in-flight HTTP requests, not just the UI.

Finishing a run

A run is complete when every stage has been approved (or auto-approved). There's no separate "submit"; the run is the record. Come back to it any time from the recent-runs list; everything it produced, including the full history of superseded attempts, is still there.

You can delete a run you no longer want from the recent-runs list; it moves to the Trash, so a mistaken delete is recoverable.

A workspace can hold more than one line of work at once — a feature you're building, a bug you're chasing, an experiment on the side. Projects keep those streams separate inside a single workspace: each one has its own run history and its own short list of the workflows it actually uses, without you juggling folders or splitting up the shared .ring record.

The Default project

Every workspace has a Default project. It's created automatically the first time you open a workspace, and it's the home for every run that isn't filed anywhere else — including all the runs you made before you had any projects. You never have to set it up, and you can't delete it. If you never create another project, nothing changes: the app looks and works exactly as it did before Projects existed.

The active project

Each window has one active project, shown in a dropdown in the toolbar next to the workspace name. The active project scopes what the window shows and where new work goes:

• Recent Runs and Search list only the runs filed under it (the Default project also sweeps in every unfiled and legacy run).
• New runs you start are filed under it automatically.
• If it pins workflows (below), the Workflows list narrows to just those.

Switching the active project re-scopes the window instantly. The choice is remembered per window, so reopening a workspace lands you back on the project you left.

Creating and switching projects

Open the Projects tool window from the briefcase icon in the left rail, or choose Manage Projects… in the toolbar's project dropdown. From there you can create a project, rename it, switch which one is active, and delete the ones you no longer need. You can switch the active project from either the Projects list or the toolbar dropdown.

Pinned workflows

A workspace's full workflow library is shared across every project, but most projects only touch a handful of workflows. Pin the ones a project uses and the Workflows list shows just those, in the order you pinned them, whenever that project is active. Pin and unpin from the Projects tool window.

Pinning is only a view. Every workflow is still runnable, and a project with no pins shows the full Built-in/Custom library exactly as before — which is why the auto-created Default project reads like a pre-Projects workspace. The Editor tab always shows the whole library, since authoring is workspace-wide.

Moving a run between projects

Filed a run under the wrong project, or want to tidy an old one into place? Right-click any run in Recent Runs and choose Move to Project. The run keeps all of its history; only which stream it belongs to changes.

Deleting a project

Deleting a project (any one but Default) removes it from the list. Its runs are not touched or lost: with no project left to claim them, they fall back to the Default project, where you'll find them again. Nothing on disk is rewritten, so a deleted project's runs keep their full provenance.

Where projects live

The set of projects and their pins is saved in your workspace's .ring/projects.json; which project is active in a window is part of that window's saved layout. A run only records which project it belongs to — the runs themselves stay in the single .ring/runs/ directory, so provenance, search, and the CLI are unaffected.

Every stage's prompt is a plain file in your workspace, and the Prompt Library is where you see them all in one place: what each prompt does, what inputs it takes, and whether it has problems — without leaving the app. It's a reference surface, not an editor: prompts stay plain files you edit in anything.

Opening the library

The library lives on the Workflows tab as a left tool window — click its icon in the rail (a closed book) or press ⌘8. It lists every .pml.md prompt in your workspace, grouped by the workflow that uses it: built-in workflows first in their sidebar order, then your own, then a trailing Not referenced by any workflow group for files no manifest points at — experiments, or leftovers from workflows you've removed. A prompt shared by several workflows appears once, listing everything that references it.

Reading a prompt

Select a prompt and the documentation view opens in the center pane:

• Header: the filename, which workflow and stages use it, whether it's built-in or yours, and its path.
• Inputs: each declared input with its description and default value. These are the {{inputs.<name>}} placeholders the prompt's body uses (see Prompt files).
• Outputs: the artifacts the prompt declares it produces, with descriptions.
• Source: the full file, exactly as it is on disk.

Copy content, Copy Path, and Reveal in Finder are in the toolbar, and the same actions (plus Open) are on each row's context menu.

When a prompt has problems

If a prompt fails to parse or declares invalid names, the library doesn't hide it — the entry stays in the list with a badge, and the documentation view lists each problem (for example, Output name "refined-spec" must match `[A-Za-z_][A-Za-z0-9_]*`.). A prompt with problems would fail at run time; the library shows you before you get there. See Troubleshooting for the common case and its fix.

Using a library prompt in a run

The execution form's Prompt File row has a Library… menu next to Browse…. It lists the same prompts, grouped by workflow with the current workflow's section first, and picking one overrides the stage's prompt for that run — same override semantics as picking a file with Browse…, including Revert. Prompts with problems are marked in the menu rather than hidden.

Refreshing

The Refresh button re-scans the prompts folder, so edits, new files, and deletions show up immediately. Refresh doesn't re-create deleted files: if you delete a built-in prompt to get a fresh copy, relaunch the app (or reopen the workspace) and the seeder restores it.

The library is read-only and available on every tier.

A single model's answer is one data point. Multi-agent execution runs a stage several ways at once and lays the results next to each other, so "which model should I trust?" becomes something you can see rather than guess. There are four modes, set in the stage's execution block.

Multi-agent modes require a license. Single-agent runs and replay are always available.

Choosing a mode

Mode	What it does	You get
parallel	Runs N agents on the same prompt at once.	Every result, side by side, to compare and choose from.
race	Runs N agents at once; the first valid success wins and the rest are cancelled.	One result, fast.
consensus	Parallel, plus a structural analysis of where the outputs agree and differ.	Agreement and divergence, made explicit.
specialist	Assigns named roles (planner, reviewer, tester…), each with its own instructions.	Complementary outputs you can promote together.

Parallel and race use agents

parallel, race, and consensus take a list of agents (2–8 of them). Each agent names a runtime, and optionally a model:

    execution:
      mode: parallel
      agents:
        - runtime: claude-code
          model: sonnet
        - runtime: openrouter
          model: anthropic/claude-opus-4.5
        - runtime: ollama

Every agent gets the identical prompt, the same consumed artifacts, and writes into its own slot directory; nothing mixes. Duplicate runtime-and-model pairs are allowed on purpose: running the same model twice is a fair way to see its variance.

Parallel finishes when every agent reaches a terminal state. The attempt succeeds if at least one agent succeeded with no blocking validation failure.

Race validates each agent the moment it finishes. The first one to succeed and pass its blocking validators wins; the others are cancelled then and there. Their partial output is still saved and marked cancelled; provenance is never thrown away. If they all fail, the attempt fails.

Consensus adds an analysis

Consensus runs exactly like parallel, then compares the outputs structurally and reports:

• the sections that appeared in every candidate,
• the sections that appeared in only some of them, and
• a pairwise similarity score to flag the odd one out.

It's an agreement-and-disagreement report for you; Ringmaster never auto-selects a winner from it. Where the models converge is usually solid; where they split is where your attention is worth most.

Specialist uses roles

Specialist mode is different in intent: the executions aren't competing, they're dividing the work. Each role gets the stage prompt plus its own instructions overlay:

    execution:
      mode: specialist
      roles:
        planner:
          runtime: claude-code
          instructions: |
            You are the planner. Produce plan.md: problem, approach, success criteria.
        security:
          runtime: claude-code
          instructions: |
            You are the security reviewer. Produce security-review.md: top three risks.

Each role's slot is named after the role. Because the outputs are complementary, the review gate lets you promote artifacts from several roles at once: keep plan.md from the planner and security-review.md from the security role. If one role fails, you can still promote the others or re-run just the one that failed.

The comparison view

Whenever an attempt has more than one execution, Ringmaster builds a comparison table: each slot's status, its validation result, how long it took, and (when the runtime reports them) token counts and cost. From there you can open any two outputs in a side-by-side diff before deciding what to promote. The same data is written to a comparison.json in the attempt directory, and you can read it from the command line with ringmaster compare (see the CLI).

How many run at once

Ringmaster caps how many executions run simultaneously (four by default) so a wide fan-out doesn't overwhelm your machine or your rate limits. You can change the cap in Settings. Some local runtimes that serve one request at a time (LM Studio, llama.cpp) are run one after another automatically, regardless of the cap.

Promotion, same as always

Multi-agent or not, the gate is the same: you review the candidates and promote the artifacts you want. Those become canonical and flow downstream. Everything you didn't pick stays in the run's history, with its provenance intact, in case you want to revisit the comparison later.

Validators are automated checks that run against a stage's output the moment an execution finishes. They're how a stage refuses to pass malformed work downstream, and how you let a stage approve itself with confidence. Each execution is validated on its own, so in a multi-agent attempt every candidate gets its own verdict.

You declare validators in a stage's validators list. Ringmaster ships three built-in types, plus a fourth that runs a script you provide.

artifact_exists

Asserts that one or more named files were produced and aren't empty.

    validators:
      - type: artifact_exists
        artifacts: [specification.md, api-reference.md]

Field	Required	Notes
artifacts	yes	The filenames that must exist in the execution's output.

markdown_sections

Asserts that a Markdown file contains specific headings. Matching is case-insensitive and works at any heading level.

    validators:
      - type: markdown_sections
        artifact: specification.md
        required: [Overview, Requirements, Assumptions, Non-Goals]

Field	Required	Notes
artifact	yes	The Markdown file to check.
required	yes	The heading texts that must be present.

This is the workhorse for spec- and plan-shaped stages: it turns "the output should cover X, Y, and Z" into a check the stage actually enforces.

json_schema

Asserts that a file parses as JSON and validates against a JSON Schema you keep in the workspace.

    validators:
      - type: json_schema
        artifact: result.json
        schema: schemas/result.schema.json

Field	Required	Notes
artifact	yes	The file to parse as JSON.
schema	yes	Path to a JSON Schema file, relative to the workflow (or absolute). Must resolve inside the workspace.

Use it when a downstream stage or an external tool has to parse the output and you need to guarantee its shape.

custom_script

Runs an executable you supply and treats its exit code as the verdict: 0 passes, anything else fails. It's how you enforce a check the built-ins don't cover, like a linter, a type-checker, or a project-specific script. This one is a Professional feature, and it runs only in the Direct build. The App Store build can't run a custom script, and a workflow that declares one is rejected there rather than skipped quietly.

    validators:
      - type: custom_script
        script: checks/validate.sh
        timeout: 30

Field	Required	Notes
script	yes	Path to the executable, relative to the workflow (or absolute). Must resolve inside the workspace.
timeout	no	Seconds to wait before the script is killed and the check fails. Defaults to 60.

The script runs in the stage's output directory, so it can read the files the stage just produced. It's run directly rather than through a shell, so it needs to be executable (chmod +x) and start with a working interpreter line. The check is fail-closed: a non-zero exit, a script that won't start, or one that runs past its timeout all count as a failure at the validator's severity, which is blocking unless you set it otherwise. When a script fails, the tail of its output is shown with the result so you can see why.

Because a custom script runs arbitrary code on your Mac with your privileges, Ringmaster asks before it runs one for the first time, naming the script and waiting for you to allow it. Your answer is remembered for that version of the workflow; edit the script or the workflow and you'll be asked again. To withdraw consent, right-click the workflow in the Workflows list and choose Revoke Custom Validator Consent. A headless CLI run has no one to ask, so it refuses custom scripts unless you pass ringmaster run --allow-custom-scripts, which is your way of saying you've reviewed the script yourself. See The ringmaster CLI.

Severity

Every validator has a severity. Add it with severity:; the default is blocking.

Severity	Effect
blocking	A failure prevents auto-approval. This is the default.
error	Shown as an error in the UI, but doesn't block.
warning	Shown as a warning.
info	Informational.

    validators:
      - type: markdown_sections
        artifact: spec.md
        required: [Overview, Requirements]
        severity: blocking
      - type: markdown_sections
        artifact: spec.md
        required: [Open Questions]
        severity: warning      # nice to have, won't block

How validators meet the gate

Validators and the review gate work together:

• A stage with review.required: false auto-approves only if it succeeds and no blocking validator fails. A blocking failure stops it for you regardless.
• A stage with the review gate on always stops for you; the validator results are shown alongside the output so you can see, at a glance, whether each candidate met its contract before you decide.

In a multi-agent attempt, the comparison table shows each candidate's validation verdict in its own column, handy when you're choosing which one to promote.

Checking a workflow's validators ahead of time

ringmaster validate confirms your validator blocks are well-formed (known types, required fields present, schema files that actually exist and resolve inside the workspace) before you ever run the workflow. See The ringmaster CLI.

Automated repair lets a stage try to fix its own blocking validation failures before they ever reach you. When a stage finishes but a blocking validator fails, Ringmaster can feed that failure back to the agent as revision context and run another attempt, up to a limit you set. If one of those attempts passes, the stage moves on as though it had succeeded the first time. If none do, it stops for you exactly as it would have anyway. You configure it per stage, in the workflow manifest.

Automated repair is a licensed feature; see Installation & licensing.

Turning it on

Add a repair: block to a stage, alongside its validators::

    validators:
      - type: markdown_sections
        artifact: spec.md
        required: [Overview, Requirements, Non-Goals]
    repair:
      enabled: true
      maxAttempts: 2
      triggeredBy: [markdown_sections]

Field	Required	Notes
enabled	no	Turns the loop on. Defaults to false.
maxAttempts	no	How many repair attempts to run after the first failure. A whole number from 1 to 10; defaults to 2.
triggeredBy	no	The validator types whose blocking failure should trigger repair. Omit it, or leave it empty, to react to any blocking failure. Otherwise list the types you care about: artifact_exists, markdown_sections, json_schema, custom_script.

What happens during a run

When an attempt finishes with a blocking validation failure that matches triggeredBy, Ringmaster gathers the specific failures, hands them back to the runtime as revision feedback ("the previous attempt failed these checks, fix them"), and runs a fresh attempt. The stage shows Repairing in the gap between attempts so you can see the loop is working rather than waiting on you.

Two ways it ends:

• It converges. A repair attempt passes validation. The stage succeeds and any downstream stages unblock, the same as a clean first run.
• It runs out. Every attempt up to the limit still fails. The stage stops at the review gate as a normal failure. Every attempt is kept, so you can read what each one tried, pick one up by hand, or revise it yourself.

The loop always runs before the human gate, never after. It runs once per initial attempt: once it has had its turn, control is yours.

Bounding the loop

maxAttempts is the stage's own ceiling. A workspace policy can also cap repair with maxRepairIterations, and the effective limit is whichever is smaller. Setting the policy value to 0 turns automated repair off for everything in its scope, which is a clean way to disable self-correction across a project without editing every workflow.

Single-agent stages only

Repair runs on single-agent stages. A multi-agent stage (parallel, race, consensus, or specialist) that sets repair.enabled: true is rejected when the workflow is validated, with a message telling you which stage to fix. Choosing between candidates is a judgment call, so those stages always come to you.

Without a license

Automated repair is a Professional feature. Without it, the loop simply doesn't run: a workflow that declares repair: still runs fine, a failing stage just stops at the review gate instead of trying to fix itself. Nothing is paywalled out of working, you only lose the self-correction.

Seeing what repair did

Repair never hides what it did. In the inspector, an attempt the loop produced is labeled Automated repair of 001, pointing at the attempt it was fixing, and its provenance records that the decision to revise was the engine's, not yours. The run's Timeline marks when each repair attempt started and whether the loop converged or ran out. All of this is visible with or without a license, because it is part of the run's record.

Replay re-runs a recorded attempt, optionally on a different runtime or model, feeding it the exact original prompt. It's how you check what a different model would have done with the same task, without rebuilding anything or hand-copying prompts.

How replay works

When you replay an attempt, Ringmaster takes the compiled prompt that attempt was sent (the one with its inputs already baked in) and feeds it, unchanged, to the target you choose. The new run is recorded as a fresh attempt that notes it was a replay of the original, so the lineage is never lost. The source attempt stays exactly as it was.

Overrides

You can keep everything the same and just re-run, or change the target:

• Runtime: replay the attempt on a different runtime.
• Model: replay on a different model (with a compatible runtime).
• Slot: for a multi-agent attempt, scope the replay to a single slot rather than the whole attempt.

A common use is to take a result a local model produced and replay it on a frontier model to see if the extra capability changes the answer, or the reverse, to check whether a cheaper or local model is good enough.

Staying local

If you want to be sure a replay won't reach for a paid provider, force it to stay local. A replay constrained this way keeps a local source attempt local and refuses to escalate to a hosted runtime. It's the safe default for experimenting at no cost, and it's how the CLI behaves when you pass --local-only.

From the app

Open the attempt you want to replay and choose Replay from its context menu. Pick a runtime and model if you want to change them, or accept the originals, and run. The result lands as a new attempt you can compare against the source.

From the command line

Replay is also a CLI command, which makes it easy to script "run this past attempt on three different models and compare":

ringmaster replay .ring/runs/<run-id> --stage draft --attempt 1 \
  --runtime gemini-api --model gemini-2.5-pro

--stage and --attempt are required; add --slot for a specific slot, --runtime/--model to retarget, or --local-only to stay offline. Full flags are in The ringmaster CLI.

Provenance

Because replay preserves the original inputs and records the link back to the source attempt, the resulting artifact's provenance tells the whole story: what it was replayed from, what changed (the new runtime or model), and everything that's true of any attempt. Replays are comparable to their sources exactly like any two attempts; see Provenance, reports & metrics.

Everything Ringmaster does is on the record. Every artifact records how it was made. You can view that record, export it in a couple of formats, or let the app roll the numbers across runs into metrics you can act on.

Provenance

Provenance is the complete lineage behind a single artifact. For any artifact, Show Provenance gathers:

• the workflow version, run, stage, and slot that produced it;
• the runtime and model that ran;
• the prompt file used, and any role overlay applied;
• the inputs it consumed (the upstream artifacts);
• the validation outcome;
• your review decision;
• git context and timestamps.

It's assembled from what Ringmaster already recorded during the run, not stored twice, so it always reflects what actually happened. You can copy a provenance record to share it, or export it as a report.

Reports

Reports turn a run into something you can hand to someone else: a reviewer, an auditor, a teammate who wasn't there. There are three kinds, each available as Markdown (for reading) or JSON (for tooling):

• Execution: one attempt's prompt, output, runtime/model, validation, and timing.
• Comparison: the side-by-side for a multi-agent attempt, including the consensus analysis when present.
• Provenance: the full lineage record described above.

Export from the app, or from the command line, which is handy in CI:

ringmaster export-report .ring/runs/<run-id> --stage spec --attempt 2 \
  --kind execution --format markdown --out report.md

The app and the CLI produce identical output, so a report you generate by hand and one your pipeline generates are the same document.

Metrics

Ringmaster aggregates the numbers across your runs so you can answer practical questions: which model actually gets picked most often, what each one costs, how long they take, how often they pass validation.

For each runtime-and-model it tracks things like execution count, success rate, validation pass rate, timeout and cancel rates, how often a human selected it when it was one of several candidates, average duration, and total and average cost (when the runtime reports it). Settings → Runtimes rolls these up across your workspaces, so over time you build an evidence base for which models are worth their cost on your kind of work, instead of going on vendor claims.

Advanced metrics and report export are licensed features; see Installation & licensing.

Trends

Metrics tell you where a workflow stands; trends tell you which way it's moving. Ringmaster buckets a workflow's runs by day or by week and charts how its cost, duration, and validation pass rate change over time. A model that's quietly getting more expensive, or a workflow whose pass rate is slipping, shows up here before it surprises you. Trends fill in once a workflow has a run or two behind it.

Cost budgets

You can set a monthly cost budget for a workspace. Ringmaster tracks your month-to-date spend against it, projects where the month is heading at the current pace, and tells you when that projection runs over. It's a guardrail rather than a brake: nothing gets blocked, you just get an honest read on the trajectory so there are no surprises at the end of the month.

Trust score

A trust score is a single, explainable read on how much a workflow has earned your confidence. You'll find it in the workflow inspector. It's built from three signals taken straight from the run history: how often runs complete, how often executions pass validation, and how often you approve what a human reviewed. Each signal is shown with the evidence behind it (for example, "9 of 10 runs completed"), and the score is only ever the average of the signals that actually have evidence, so a workflow you haven't reviewed yet isn't marked down for it. A brand-new workflow with no history doesn't get a fake zero; it has no score until there's something to base one on.

Trends, budgets, and the trust score are licensed features, alongside the metrics they build on.

Timeline

Every run also keeps an append-only event log. The Timeline view replays it (each attempt start, state change, and completion in order) and lets you filter by stage, agent, or event type to follow one thread through a busy multi-agent run. It's the low-level companion to provenance: provenance tells you about an artifact, the timeline tells you about the run as it unfolded.

As your run history grows, you need ways back into it: the run you did last Tuesday, every run on a release branch, the ones that cost the most, or simply others like the one you're looking at. Search and similar runs are how you find them. Both are free in every edition, because a record you can't search isn't much of a record.

Searching runs

Open the Search tool window from the magnifying glass in the left rail, or run Search Runs… from the command palette. Type to filter, and narrow with the structured filters:

• Text matches a run's ID, its workflow, its folder name, and the git branch any of its attempts ran on.
• Workflow, git branch, and runtime narrow to runs that used a particular one.
• A date range bounds when the run was created.
• Completeness limits to runs that finished, or to ones still in progress.

Search is scoped to the window's active project — you're looking within the current stream of work — and the Default project also includes every unfiled and legacy run.

Results are listed most recent first. Each row shows the workflow, the run ID, when it ran, its branch, how many attempts it has, whether it completed, and the total cost when the runtimes reported one. Click a row to open the run; right-click for Open Run, Copy Run ID, and Reveal in Finder.

Text search covers identifiers and branches, not the contents of prompts or outputs. Full-text search over the work itself is planned; for now, search finds runs, and provenance tells you what's inside one.

Similar runs

When you're looking at an attempt and want to know how the same workflow has gone before, open the Similar Runs section in the inspector. It lists other runs of the same workflow, the ones on the same workflow version first, since those are the closest comparison. It loads only when you expand it, so it costs nothing until you ask. If the workflow has no other runs yet, it says so rather than inventing matches. Click any result to open it, the same as in search.

Opening a result

Search results and similar runs both open into the center of your workspace, right where a run from the recent-runs list would. Nothing is copied or moved; you're just navigating your own history.

Every time you approve, reject, or send back an attempt, Ringmaster records the decision: what you decided, why, and on what. Over a few projects that becomes a real body of knowledge about how your team judges work. The Decisions view lets you search it. Like run search, it's free in every edition.

What's recorded

A decision is one verdict on one attempt. It captures:

• the kind of decision: approved, rejected, revision requested, merged, rerun requested, or flagged for follow-up;
• your note and any promotion reasons you gave;
• whether the decision overrode a blocking validation failure (you approved something that didn't pass its checks, on purpose);
• whether it came from a human, an automatic rule, or an automated-repair loop;
• the workflow, stage, run, and when it happened.

These are read straight from each run's record when you search, so the Decisions view always reflects what actually happened, and a run you've deleted simply drops out.

Searching decisions

Open the Decisions tool window from the left rail, or run Search Decisions… from the command palette. Filter by:

• Text, which matches the note, the promotion reasons, and the workflow, stage, and run identifiers.
• Workflow, to focus on one.
• Kind, to see only approvals, only rejections, and so on.
• Overrides only, to find the moments someone approved past a blocking validation failure, which are exactly the decisions worth revisiting.
• Origin, to separate human calls from automatic ones and from automated repair.
• A date range.

Each result shows the decision kind, its origin, whether it was an override, a one-line summary from your note or the first promotion reason, and the workflow and stage it was on.

Opening the source run

Click any decision to open the run it was made on, so a verdict is always one click from the work it was about. Right-click for Open Run, Copy Run ID, and Reveal in Finder.

Decisions for one workflow

To see a single workflow's history of decisions, right-click it in the Workflows list and choose Past Decisions. That opens the Decisions view already filtered to that workflow, which is the fastest way to answer "how have we handled this one before."

A workflow is rarely just one file. It usually carries prompt files, JSON schemas, and sometimes a custom validator script. A package bundles all of that into a single folder you can hand to someone else, with a checksum for every file so the other side can tell it arrived intact. Exporting a package is a Professional feature; importing one is always free.

What's in a package

A package is a plain folder with a package.json manifest at its root and the workflow's files alongside it. The manifest records the package's name and version, a content hash for the workflow, and an entry for every bundled file: the prompts, the schemas, any custom-validator scripts, and the workflow YAML itself. Each entry carries a SHA-256 checksum of that file's bytes.

Those checksums are the point. They let an import verify that nothing was lost or altered in transit. They detect corruption and casual edits; they are not cryptographic signatures, so they don't prove who made the package. Signed packages are planned for a later release.

Exporting

In the app, right-click a workflow in the Workflows list and choose Export as Package…, or use Export as Package… on the Editor tab. From the command line:

ringmaster package export workflow.yaml --out ./dist --package-version 1.2.0

--out is the folder to write into (the current directory by default), and --package-version stamps the manifest (1.0.0 by default). Export gathers the workflow's prompts and schemas, copies them with their checksums, and writes the manifest. If you don't hold a Professional license, the app explains what's needed and the CLI exits with its licensing code; see The ringmaster CLI.

Importing

In the app, use Import Package… on the Editor tab. From the command line:

ringmaster package import ./dist/my-workflow --into ./workflows

--into is the workflows folder to install into (the current directory by default). Import is free, and it is careful: before it copies anything, it checks every file against its recorded checksum, confirms the workflow matches the hash in the manifest, and makes sure no file path points outside the package. A package that is incomplete, modified, or tries to escape its own folder is refused with a message that says which check failed, and nothing is installed. A custom-validator script keeps its executable bit so it's ready to run on the other side, subject to the same consent prompt as any custom script.

Ringmaster treats agents as interchangeable execution engines. A workflow names a runtime by a short ID; swap the ID and the same workflow runs somewhere else. Runtimes come in three shapes: CLI agents you've installed, local model servers running on your machine, and hosted APIs. Settings → Runtimes shows which are available right now, with a hint telling you what to do if one isn't.

Quick reference

Runtime ID	Name	Type	Setup
claude-code	Claude Code CLI	CLI agent	Install the claude CLI on your PATH
codex-cli	Codex CLI	CLI agent	Install codex; set OPENAI_API_KEY
copilot-cli	GitHub Copilot CLI	CLI agent	Install copilot; set GH_TOKEN (or GITHUB_TOKEN)
gemini-cli	Gemini CLI	CLI agent	Install gemini; set GEMINI_API_KEY (or GOOGLE_API_KEY)
kiro-cli	Kiro CLI	CLI agent	Install kiro-cli; sign in through Kiro
lm-studio	LM Studio	Local server	Run the LM Studio server; load a model
ollama	Ollama	Local server	ollama serve; ollama pull <model>
vllm	vLLM	Local server	vllm serve <model>
llama-cpp	llama.cpp	Local server	llama-server -m <model.gguf>
gemini-api	Gemini API	Hosted API	Add an API key in Settings → Gemini
openrouter	OpenRouter	Hosted API	Add an API key in Settings → OpenRouter
nvidia	NVIDIA NIM	Hosted API	Add an API key in Settings → NVIDIA
custom-openai:<id>	Custom OpenAI-compatible	Hosted API	Define a profile in Settings → OpenAI
custom-anthropic:<id>	Custom Anthropic-compatible	Hosted API	Define a profile in Settings → Anthropic

CLI agents

These shell out to an agent CLI you've installed. Ringmaster looks for the executable on your PATH (including the usual Homebrew locations), and the Runtimes panel shows it as available once it's found.

• Claude Code (claude-code): install the claude CLI. It uses its own auth; if you've signed in through Claude Code, Ringmaster uses that. Models: sonnet (default), opus, haiku — stable aliases the CLI resolves to its current versions.
• Codex (codex-cli): install codex and set OPENAI_API_KEY.
• Copilot (copilot-cli): install copilot and set GH_TOKEN (or GITHUB_TOKEN).
• Gemini (gemini-cli): install gemini and set GEMINI_API_KEY (or GOOGLE_API_KEY).
• Kiro (kiro-cli): install kiro-cli and sign in through Kiro's own login. It manages its own model.

For Codex, Copilot, and Gemini, the model picker offers (use CLI default) — the tool's own current default — plus a Custom field for any model ID the CLI accepts. Ringmaster deliberately doesn't ship a hardcoded model list for these: the CLIs update faster than any list would, and a stale pin is worse than none.

If a CLI isn't found, the Runtimes panel says so and tells you the command it expected. Install it, put it on your PATH, and reselect the runtime.

Local model servers

These run a model on your own machine and Ringmaster talks to them over HTTP. Nothing leaves the Mac, and there's no API key, which makes them a good fit for getting started and for private work.

• LM Studio (lm-studio): install the app, open the Developer tab, start the server, and load a model. Default endpoint http://localhost:1234. Ringmaster lists whatever models you've loaded.
• Ollama (ollama): run ollama serve, then ollama pull <model> (for example ollama pull llama3.1). Ringmaster discovers your pulled models automatically.
• vLLM (vllm): start it with vllm serve <model>. Default endpoint http://localhost:8000.
• llama.cpp (llama-cpp): start llama-server -m <path/to/model.gguf>. Default endpoint http://localhost:8080.

If a server isn't reachable or has no model loaded, the Runtimes panel says which and how to fix it. LM Studio and llama.cpp serve one request at a time, so Ringmaster runs their executions one after another even inside a parallel stage.

Hosted APIs

These call a provider's API over the network. You add the key once in Settings; it's stored in your macOS Keychain. After you add or rotate a key, Ringmaster asks you to relaunch so it picks up the new value.

• Gemini API (gemini-api): add a key in Settings → Gemini (create one at aistudio.google.com/apikey). Ringmaster lists the current Gemini models.
• OpenRouter (openrouter): add a key in Settings → OpenRouter (create one at openrouter.ai/keys). OpenRouter brokers hundreds of models from many providers; openrouter/auto lets it choose.
• NVIDIA NIM (nvidia): add a key in Settings → NVIDIA (create one at build.nvidia.com). NVIDIA's hosted catalog (Llama, Nemotron, DeepSeek, Qwen, Mistral) behind one OpenAI-compatible endpoint, with free credits to start. Ringmaster lists the current NIM models.

Custom endpoints

If you run your own gateway, a proxy, or any service that speaks the OpenAI or Anthropic wire format, add it under Settings → OpenAI (OpenAI-compatible) or Settings → Anthropic (Anthropic-compatible). A profile has a name, the base URL, an API key (kept in the Keychain), and, if the endpoint doesn't advertise its models, a manual list of model IDs. Each profile becomes a runtime: custom-openai:<your-id> or custom-anthropic:<your-id>, usable in any workflow. Public endpoints must use HTTPS; http:// is allowed only for local hosts.

Pinning models in a workflow

Any runtime that supports model selection can be pinned per stage, or per agent in a multi-agent stage, with model:. Ringmaster passes the model ID straight through, so anything the provider accepts works; you're not limited to the ones listed above. An ID the provider rejects fails at run time with the provider's own error.

    runtime: openrouter
    model: anthropic/claude-opus-4.5

ringmaster is the companion command-line tool. It runs the same workflows as the app, against the same workspaces and run history, with no UI, which makes it the way to put Ringmaster in CI, batch jobs, and scripts. Its exit codes are stable and documented, so a pipeline can branch on them.

The CLI is distributed as a signed, notarized standalone binary. Put it on your PATH and you're set.

Commands at a glance

ringmaster version
ringmaster providers list
ringmaster validate <workflow>
ringmaster run <workflow>
ringmaster replay <run>
ringmaster compare <attempt-dir>
ringmaster export-report <run>
ringmaster dataset build
ringmaster eval <dataset>
ringmaster package export <workflow>
ringmaster package import <package>

Every command takes --help. Add --json to the ones that support it for machine-readable output; the plain-text output is meant for humans, so use --json whenever a script needs to parse the result.

version

ringmaster version

Prints the version and build number.

providers list

ringmaster providers list
ringmaster providers list --json

Lists the runtimes, whether each is available in this environment, and the models it offers. With --json you get an array of objects (id, displayName, runsLocally, available, availabilityHint, models, …), useful for asserting a runner has what a workflow needs before you run it.

validate

ringmaster validate path/to/workflow.yaml

Checks a workflow without running it: schema, identifiers, stage references, runtime IDs, and validator config. Exits 0 if valid, 2 if not. Add --json for a structured diagnostic report. This is the natural first step in any pipeline.

run

ringmaster run path/to/workflow.yaml [--auto-approve] [--acknowledge-policy] [--allow-custom-scripts] [--output <dir>] [--json]

Runs a workflow headlessly, advancing as far as the automation rules allow and stopping at the points that need a human. It stops at a review gate, a candidate that needs selecting, a blocking validation failure, a policy that requires approval, a licensing refusal, or a pre-flight error.

Flag	Effect
--auto-approve	Plain-approve a succeeded single-agent or race attempt that has no blocking validation failures. It never selects among multiple candidates and never overrides validation.
--acknowledge-policy	Proceed past a stage whose policy requires approval. Recorded in the run's events. Mirrors the app's "Approve and Run".
--allow-custom-scripts	Permit custom_script validators, the headless stand-in for the app's consent prompt. Without it, a stage with a custom script is refused at pre-flight. Pass it only when you've reviewed the script.
--output <dir>	Write runs somewhere other than the workspace's .ring/runs/, handy for throwaway CI artifacts.
--json	Emit one JSON object per lifecycle event, then a final summary object, on stdout.

The JSON summary includes the run ID and directory, why it stopped, the exit code, and per-stage the canonical artifact paths the approved attempt produced.

replay

ringmaster replay .ring/runs/<run-id> --stage <id> --attempt <n> \
  [--slot <id>] [--runtime <id>] [--model <id>] [--local-only] [--json]

Re-runs a recorded attempt, feeding it the original prompt and inputs. --stage and --attempt are required. Use --runtime/--model to retarget, --slot to scope to one slot of a multi-agent attempt, and --local-only to refuse any escalation to a paid provider. See Replay.

compare

ringmaster compare .ring/runs/<run-id>/stages/<stage>/attempts/<n>

Prints the comparison table and consensus block for a multi-agent attempt. --json emits the raw comparison.json.

export-report

ringmaster export-report .ring/runs/<run-id> --stage <id> --attempt <n> \
  [--kind execution|comparison|provenance] [--format markdown|json] [--out <file>]

Exports a report for an attempt. --kind defaults to execution, --format to markdown. Without --out it writes to stdout. The output is byte-for-byte the same as the app's export.

dataset

ringmaster dataset build [--workspace <dir>] [--workflow <id>] [--stage <id>] \
  [--status <status>] [--name <name>] [--out <file>]

Builds an eval dataset by querying your run index: it gathers matching attempts into a portable list you can replay later. With no filters it takes every approved attempt; narrow it with --workflow, --stage, or --status. Writes JSON to --out, or to stdout. A Professional feature.

eval

ringmaster eval <dataset> [--workspace <dir>] [--runtime <id>] [--model <id>] \
  [--local-only] [--format markdown|json] [--out <file>]

Replays a dataset against a candidate model and emits a regression report: for each entry it compares the candidate's validation result, cost, duration, and output against the recorded baseline, then summarizes what improved, what regressed, and what held steady. Name the candidate with --runtime/--model (omit them to re-run on the original), and use --local-only to refuse any escalation to a paid provider. --format defaults to markdown; --out writes to a file instead of stdout. A Professional feature.

It exits 0 when nothing regressed, 2 when at least one entry's validation regressed (a baseline that passed now fails), and 7 when the dataset produced nothing to compare, so a pipeline can tell a real regression apart from an empty evaluation.

package

ringmaster package export <workflow.yaml> [--out <dir>] [--package-version <version>]
ringmaster package import <package-dir> [--into <dir>]

Bundles a workflow and its files into a shareable, checksummed package, or installs one. export writes a package folder (a Professional feature); import is free and verifies every file against its checksum before installing, refusing anything incomplete or modified. See Workflow packages for the full story.

Exit codes

The codes are a frozen contract, safe to branch on in CI.

Code	Meaning	Commands
0	Success	all
1	Usage or internal error (bad arguments, missing file, write error)	all
2	Validation failure: an invalid workflow, a blocking validation failure at run time, a package that fails its integrity check, or a validation regression in eval	validate, run, replay, eval, package
3	Stopped at a review gate: the hand-off worked; open it in Ringmaster to review	run
4	Policy refusal (a stage needs approval; pass --acknowledge-policy)	run, replay
5	Licensing refusal (a gated mode or feature without the entitlement)	run, eval, dataset, package
6	Pre-flight failure (a provider is unavailable, a credential is missing, or a custom script wasn't allowed)	run
7	Nothing to evaluate (the dataset produced no comparison)	eval

Credentials in CI

A headless run never prompts the Keychain; it reads credentials from the environment. For each hosted API, Ringmaster checks its own RINGMASTER_* variable first, then the provider's conventional one:

• Gemini API: RINGMASTER_GEMINI_API_KEY, then GEMINI_API_KEY, then GOOGLE_API_KEY
• OpenRouter: RINGMASTER_OPENROUTER_API_KEY, then OPENROUTER_API_KEY

CLI-agent subprocesses inherit the environment unchanged, so their usual variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, and so on) flow straight through. Local servers need no credentials. A missing credential fails pre-flight (exit 6) with a message naming the variable it wanted.

A CI example

# Fail the build if the workflow is malformed.
ringmaster validate workflow.yaml || exit 1

# Run it; treat "stopped at a review gate" as a soft stop, anything else as failure.
ringmaster run workflow.yaml --auto-approve --output "$RUNNER_TEMP/runs" --json
case $? in
  0) echo "completed" ;;
  3) echo "stopped at review gate: open in Ringmaster"; exit 1 ;;
  *) echo "run failed"; exit 1 ;;
esac

Sharing a workspace with the app

The CLI and the app can work the same workspace safely. They can't touch the same run at the same time; Ringmaster marks a run with a writer lock while it's active, and the other process will refuse it rather than corrupt it. Licensing behaves exactly as in the app: single-agent runs and replay always work; gated modes need an active license and refuse at pre-flight with the same message you'd see in the UI.

The fastest way to find any action is the command palette: press ⇧⌘P and start typing. It lists every context action available right now, so you rarely need to memorize anything. That said, a handful of shortcuts are worth keeping in your fingers.

App-wide

These work whenever a workspace window has focus.

Shortcut	Action
⇧⌘P	Open the command palette
⇧⌘O	Open a workspace
⌘,	Settings
⇧⌘0	Toggle the left panel
⇧⌘I	Toggle the right panel
⇧⌘T	Toggle the bottom drawer
⇧⌘A	Show Artifacts
⌘1 … ⌘8	Select a left tool window (⌘8 is the Prompt Library)
⌥⌘1 … ⌥⌘5	Select a right tool window
⌥⌘C	Copy Provenance (the record, not the file)

While running a stage

These act on the stage you're looking at, and live on the execution status bar so they go through the right confirmations (cancel prompts, policy approvals).

Shortcut	Action
⌘R	Run, or re-run, the stage
⇧⌘R	Replay the attempt
⌘E	Iterate / Revise: run another pass with feedback (single-execution stages; see iteration)
⇧⌘⏎	Approve / un-approve the attempt
⌘.	Cancel

In the Artifacts and Files lists

Shortcut	Action
Space	Quick Look the selected file
⌘⌫	Move to Trash (Files list)

If you ever forget one, ⇧⌘P and the menu bar both show the binding next to each command.

The Direct build updates itself

The Direct (Developer ID) build has a built-in updater. It checks quietly for a new version when the app launches, and again periodically while it's running. When an update is available it offers it; you decide when to install. Nothing nags, and a failed check (no network, say) passes silently rather than interrupting you.

To check on demand, choose Check for Updates… from the app menu.

Updates are delivered over an authenticated, signed channel: Ringmaster fetches the update feed as your licensed account, downloads are verified against a built-in signing key before anything is installed, and the download links themselves are short-lived. In practice this is invisible (you click update and it updates), but it means an update can't be spoofed or served to an unlicensed copy.

The App Store build updates through the App Store

The Mac App Store build doesn't include the built-in updater, because the App Store handles updates itself. You'll get new versions the usual way, through the App Store's Updates tab (or automatically, if you have that turned on). There's no Check for Updates… item in this build.

Which build do I have?

If the app menu has a Check for Updates… item, you're on the Direct build. If it doesn't, you installed from the App Store. Both are the same application; they only differ in how they're delivered and updated. See Installation & licensing.

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.