Configuration

Irigate reads ~/.config/irigate/config.yaml by default. IRIGATE_CONFIG selects another file, and an explicit --config argument overrides both. Profiles are validated before any upstream process starts.

Broker fields

The profile requires name and a non-empty upstreams mapping. host defaults to 127.0.0.1, port defaults to 8765, and runtime_report_path is optional.

Only localhost or IP loopback listener addresses are accepted. The profile name labels validation output and runtime reports; it does not change routing.

Upstream fields

Each upstream key becomes the prefix in <upstream-key>__<tool-name>. Keys must start with a lowercase letter and may contain lowercase letters, digits, and hyphens.

Supported upstream fields are description, transport, command, args, execution, wsl_path_arguments, cwd, env, inputs, shareable, qualifier, concurrency, call_timeout_seconds, idle_timeout_seconds, failure_threshold, and crash_threshold. transport supports only stdio; command and idle_timeout_seconds are required. execution defaults to native.

Use the root README configuration section for the complete field table.

Credential references

Environment values must reference broker-process variables:

env:
  CONTEXT7_API_KEY: ${CONTEXT7_API_KEY}

Do not put credentials in URLs, query parameters, command arguments, logs, or committed profiles. Irigate resolves the referenced value from the broker process without writing it into validation output, audit records, or runtime reports.

Windows applications from WSL

Set execution: wsl-windows when Irigate runs in WSL and the upstream command is a Windows executable. Irigate selects the newest live WSL interop socket immediately before every process spawn instead of retaining the broker shell’s inherited endpoint. This keeps long-running brokers working after the shell that started them exits.

upstreams:
  pencil:
    command: "/mnt/c/Users/<Windows-user>/AppData/Local/Programs/Pen/resources/app.asar.unpacked/out/mcp-server-windows-x64.exe"
    args: ["--app", "desktop"]
    execution: wsl-windows
    wsl_path_arguments:
      # filePath is the open .pen document path used across Pencil tools.
      "*": ["/filePath"]
      # These are exact Pencil MCP tool names and request fields.
      export_html: ["/outputPath"]
      export_nodes: ["/outputDir"]
    env: {}
    shareable: false
    concurrency: serial
    idle_timeout_seconds: 300

Replace <Windows-user> with the Windows account directory under /mnt/c/Users. wsl_path_arguments is explicit and accepted only with execution: wsl-windows; Irigate does not infer either setting from .exe suffixes or /mnt/c paths.

The mapping keys are MCP tool names, and each value is a JSON Pointer into that tool’s request object—not a configured filesystem directory. export_html and export_nodes are current Pencil MCP tool names; outputPath and outputDir are fields in their published request schemas. The actual paths arrive later in each MCP call.

For example, a client could send filePath: /home/<WSL-user>/designs/dashboard.pen, which becomes a \\wsl.localhost\\<distribution>\\home\\<WSL-user>\\designs\\dashboard.pen path for Pencil. It could send outputPath: /mnt/c/Users/<Windows-user>/Documents/pencil-export/dashboard.html or outputDir: /mnt/c/Users/<Windows-user>/Documents/pencil-export/assets, which become C:\\Users\\<Windows-user>\\Documents\\pencil-export\\dashboard.html and C:\\Users\\<Windows-user>\\Documents\\pencil-export\\assets. These locations are examples supplied by the caller; Irigate does not create or select them in the profile.

Missing pointers and Windows or other non-POSIX strings pass through; slash-prefixed Windows drive paths such as /C:/Users/example/design.pen are normalized directly. A configured non-string value fails closed. Rendered {workspace} process arguments are converted automatically. Protected payload logs preserve the original client-facing arguments.

You normally do not need to construct this mapping manually. After adding the Windows upstream, inspect its live MCP schemas and repair the profile:

irigate doctor --config ~/.config/irigate/config.yaml
irigate doctor --config ~/.config/irigate/config.yaml --apply

The first command is read-only and reports whether repair is needed. --apply adds schema-derived file and directory fields while preserving existing mappings, comments, and unrelated profile content. It validates a temporary profile, creates <profile>.irigate-doctor.bak on the first repair, and replaces the profile atomically. Run it again after upgrading the Windows MCP server so newly advertised path fields are detected.

If no live WSL interop endpoint exists, process startup fails with a restart instruction instead of a raw Broken pipe error. MCP application errors from the Windows server remain tool-level errors—for example, Pencil can report that a document must be open without being classified as a process crash or counted toward a shared upstream’s degradation thresholds.

Per-session input

The profile model accepts one dynamic input: a required workspace directory on a non-shareable upstream. It requires exactly one standalone {workspace} argument placeholder and a non-empty allowed_roots list. A filesystem server is one possible consumer, not part of the input contract itself.

Each configured root permits its canonical directory and all descendants. Profile-side leading ~ and ${ENV_NAME} references expand under strict rules; environment-derived roots must be absolute. Canonical matching rejects traversal, sibling-prefix confusion, nonexistent paths, files, and symlink escapes.

Namespaced client inputs are parsed, canonicalized, fixed for each downstream MCP session, and rendered into the isolated worker’s arguments.

Reload behavior

While serving, Irigate watches the selected profile. Changed active upstreams must initialize successfully before routing switches. Added and changed dormant upstreams remain stopped until selected.

Invalid updates, missing environment references, and failed upstream initialization leave the last valid active configuration available. Changes to host or port require restarting the broker.

Sharing and isolation

Upstreams are isolated by default. shareable: true requests shared mode, but sharing is admitted only by a registered upstream-specific qualifier. Context7 is qualified shared in profiles/mvp.yaml; code-review-graph remains isolated because it retains context-bound state.

Failed qualification downgrades the selected upstream to isolated mode. With --require-qualified-sharing, the first selected use is rejected instead.

Related pages

Use Agent selection to narrow what each client sees, and Safety for the credential and telemetry boundary.