Configuration

Everything rupu reads from config.toml — every section and key, its type, its default, and what it does. All keys are optional: an empty file (or no file) is a working configuration.

Files and layering

rupu reads up to three TOML files and merges them, most specific last:

Scalars and tables from a more specific layer override the less specific one; arrays replace rather than merge (a project that declares [[scm.rules]] replaces the global list). Resolution order, highest first:

# highest wins
global lock  ›  customer lock  ›  project  ›  customer  ›  global  ›  built-in default

Sections are strict: an unknown key inside a section such as [bash], [cp] or [netflow] is a parse error rather than a silently ignored typo. A few retired keys are still accepted as no-ops — see Deprecated keys.

Environment variables

There is no environment layer — environment variables are never merged into the config. A handful are read directly by the code they affect and win over the matching key there:

Reading and editing

rupu config get ui.theme
rupu config set cp.gate_sweep_interval_secs 30
rupu config set update.channel beta

rupu config get / set work on the global file only. Dotted keys descend into tables; the value is parsed as a TOML scalar (string, integer or bool), and set refuses to replace a table with a scalar or the reverse. Edit arrays and tables ([[scm.rules]], [recovery].fallbacks) by hand, a customer layer with rupu customer edit <slug>, or everything from the control plane's Settings page, which shows each effective value with the layer it came from, a lock toggle, and a raw TOML editor.

Locks and policy — [policy]

# ~/.rupu/config.toml — no project or customer can loosen these
permission_mode = "readonly"

[policy]
lock = ["permission_mode", "bash.env_allowlist"]

Customer layer

Assign a project to a customer with rupu customer assign <slug> (a slug is 1–63 of a-z, 0-9, -; none is reserved). The customer's config.toml then sits between the global and project files for every run in that project — and its subdirectories, since a run uses the nearest assigned ancestor of its working directory.

# ~/.rupu/customers/northwind/config.toml
default_provider = "anthropic-northwind"

[[scm.rules]]
owner   = "northwind-labs"
account = "github-northwind"

[policy]
lock = ["default_provider"]   # a repo's .rupu/config.toml can't move these runs

• Accounts are declared once, globally (rupu auth login --account anthropic-northwind --kind anthropic); the customer layer only references them.
• Arrays replace, as between global and project: a customer that declares [[scm.rules]] replaces the global rules for its projects. The project still wins on any key the customer has not locked; a customer lock cannot unlock a key the global [policy].lock names.
• A run records the customer it ran under ("customer": null when it ran with none); workflow resume / approve run on what was recorded even if the project was reassigned since, and a recorded customer that no longer exists fails the resume. Only a run from before customers existed falls back to the directory it was launched from. An autoflow run uses its repo's checkout, not its issue worktree.
• A dangling assignment or an unparseable customer layer fails the run — it never falls back to global.
• rupu customer show <slug> prints the effective config with sources and locks; rupu customer edit <slug> edits and validates the layer. The control plane manages customers, filters its lists by ?customer= and previews a launch's accounts.

More in Customers.

Top-level keys

Model providers — [providers.<account>]

One table per provider account: a bare vendor name (anthropic, openai, gemini, copilot), a named account of a vendor (anthropic-work with kind = "anthropic"), or an openai-compatible endpoint you name yourself. An agent's provider: names the account. Narrative: Providers & Auth.

[providers.anthropic]
default_model = "claude-sonnet-4-6"
max_concurrency = 6

[providers.lab-llm]              # an OpenAI-compatible endpoint
kind = "openai-compatible"
base_url = "http://10.0.0.20:8000/v1"
default_model = "qwen3-coder"
models = [{ id = "qwen3-coder", context_window = 131072, max_output = 8192 }]

An openai-compatible account must set base_url and default_model, and may not reuse a reserved name (anthropic, openai, gemini, copilot, local, github, gitlab, linear, jira).

SCM and trackers — [scm.*], [[scm.rules]], [issues]

[scm.github]
clone_protocol = "ssh"

[scm.gh-work]
kind = "github"
base_url = "https://ghe.example.com/api/v3"

[[scm.rules]]
owner = "example-corp/*"
account = "gh-work"

[[scm.rules]]
path = "~/Code/work/*"
account = "gh-work"

See Integrations for the full routing story.

Terminal UI — [ui]

Custom themes live in ~/.rupu/themes/ or a project's .rupu/themes/. rupu ui themes lists what's available (marking the current one); rupu ui theme show|validate|import manages them, and import accepts native rupu theme files and Base16 schemes.

[ui]
live_view = "compact"
pager = "never"

[ui.palette]
theme = "tokyo-night"

[ui.syntax]
theme = "base16-mocha.dark"

The bash tool — [bash]

Machine limits — [runtime]

Child runs — [dispatch]

Child runs an agent starts with dispatch (see Agents).

Message spaces — [messaging]

A run's message space (see Messaging).

Workflow run: steps — [workflow]

[workflow]
run_step_enabled = true
run_step_allowlist = ["python3", "make"]

Recovery — [recovery]

What happens when a model's reply can't be used or the provider fails the request. Background: Recovery & reliability.

[recovery]
fallbacks = [
  { model = "claude-sonnet-5-5" },
  { provider = "openai-codex", model = "gpt-5.6-cyber" },
]
server_side_fallback = true

Findings — [findings]

rupu findings import reads the size limits from the global file only. See Findings.

Concern catalogs — [coverage]

How a run's concern catalog is rendered into its system prompt; see Coverage for render modes.

Network capture — [netflow]

[netflow]
asn_source_url = "https://mirror.internal.example/ip2asn-combined.tsv.gz"
asn_refresh_interval_days = 30
subprocess_linger_ms = 5000

See Netflow.

Control plane — [cp]

Background loops rupu cp serve runs in-process, so autoflows, triggers and gate timeouts work with no external cron.

The loop toggles and intervals below, like agentiflow.reaper_enabled and netflow.asn_auto_refresh, are read once when cp serve starts: change them and restart it. Saving the global config from the control plane lists the ones you changed as restart_required; every other key applies at once.

Agentiflow supervision — [agentiflow]

See Agentiflows.

Event triggers — [triggers]

[triggers]
poll_sources = [
  "github:example-org/api",
  { source = "linear:team-1234", poll_interval = "10m", account = "linear-ops" },
]

See Triggers.

Autoflow defaults — [autoflow]

See Autoflows.

Pricing — [pricing]

Turns token counts into USD for rupu usage, run listings and the control plane. Lookup order: [pricing.<provider>."<model>"] override → built-in table (each vendor's standard-tier list rate) → [pricing.agents.<agent>]. A named account prices through its kind, and an account-level override beats the vendor one. Model ids match exactly, then with a trailing [tag] stripped, then with a date snapshot stripped.

[pricing.anthropic."claude-sonnet-4-6"]
input_per_mtok = 3.0
output_per_mtok = 15.0
cached_input_per_mtok = 0.30
cache_write_per_mtok = 3.75

[pricing.lab-llm."qwen3-coder"]    # an openai-compatible account
input_per_mtok = 0.4
output_per_mtok = 1.2

[pricing.agents.triage-bot]        # fallback when no model price is known
input_per_mtok = 0.5
output_per_mtok = 1.5

Retention — [storage]

Updates — [update]

Deprecated keys

These still parse — so an old file doesn't lose every other setting — but drive nothing. Loading one logs a warning; delete them, as a future release will reject them.