---
title: "Configuration Atlas"
description: "Searchable table of every configuration key across orchid.yml and agents.yaml — filter by name, type, or description."
package: cross-cutting
section: configuration
html_url: https://orchestratorindex.com/configuration
markdown_url: https://orchestratorindex.com/configuration.md
---

# Configuration Atlas

This page provides a searchable, filterable table of every configuration key across both config formats. Click any key to jump to its detailed reference page — [Infrastructure](/configuration-reference/infrastructure) for `orchid.yml` keys, [Agents](/configuration-reference/agents) for `agents.yaml` keys.

Orchid supports two configuration formats with identical capabilities. Choose the one that fits your workflow — or mix both in hybrid mode.

**YAML** uses two files: `orchid.yml` for infrastructure and `agents.yaml` for agent behavior. Every key maps to an environment variable; real env vars always win. This is the original format, well-suited for programmatic generation and CI pipelines.

**Markdown** uses `orchid.md` for infrastructure and `agents/*.md` for per-agent configs. Each agent file has YAML frontmatter for structured fields and a Markdown body that becomes the system prompt directly — no YAML string escaping or multi-line block scalars. An on-demand SHA-256 watcher detects file changes and rebuilds the graph without restarting.

Both formats produce identical `OrchidAgentsConfig` output. The tables below cover all keys regardless of format.

---

## Infrastructure Config

Runtime and infrastructure keys. In YAML these live in `orchid.yml`; in Markdown they are the frontmatter of `orchid.md`. Keys map to flat environment variables through `YAML_TO_ENV` (plus an API-specific subset); when the same variable is set in both the config file and the environment, the environment wins.

> Check your config file into version control for structure and non-secret defaults (model names, URLs, feature flags). Inject secrets (`*_API_KEY`, database DSNs with passwords) exclusively via environment variables or a secrets manager — never store them in YAML or frontmatter.
> 
> *info note.*

> Setting `auth.dev_bypass: true` removes all authentication and authorization. Any caller can impersonate any user. Never deploy with this enabled.
> 
> *info note.*

The full filterable configuration reference is rendered on the [Configuration Atlas](/configuration) page.

---

## Agent Behavior Config

Agent behavior and orchestration configuration. In YAML these live in `agents.yaml`; in Markdown they are individual `agents/<name>.md` files with YAML frontmatter + Markdown body. Validated against `OrchidAgentsConfig` at startup — strict sections reject unknown keys, so most typos surface immediately. Defaults cascade: values set under `defaults:` apply to every agent unless overridden per-agent.

> Enable sliding-window summarization for long-running chat sessions with token-priced LLMs. When enabled, the supervisor compresses older turns via a cheap LLM call and keeps only the most recent `history_summary_recent_turns` exchanges verbatim. Disable for short-form workflows or real-time pipelines where the summarization call adds latency with no benefit.
> 
> *info note.*

> Default to `none` for local MCP servers that share the process or a private network — no credentials needed. Use `passthrough` when the MCP server trusts your bearer token (same identity provider). Use `oauth` when each user must independently authorize the MCP server; Orchid discovers everything from the server's `401` response via RFC 9728/8414/7591 — no credentials needed on the happy path. For servers that don't implement discovery, seed explicit endpoints and credentials with `auth.manual_registration`.
> 
> *info note.*

> Always configure a fallback model in production environments. Pairing a cloud-hosted primary (e.g. `gemini/gemini-2.5-flash`) with a local Ollama model as a fallback ensures the service degrades gracefully during provider outages or rate-limit events rather than returning errors to users.
> 
> *info note.*

The full filterable configuration reference is rendered on the [Configuration Atlas](/configuration) page.

---

## Load Modes

| Mode | Root File | Agent Configs | Detection |
|------|-----------|---------------|-----------|
| YAML | `orchid.yml` | `agents.yaml` | `.yml` or `.yaml` extension |
| MD | `orchid.md` | `agents/*.md` | `.md` extension |
| Hybrid | `orchid.yml` | `agents/*.md` | `AGENTS_CONFIG_PATH` points to a directory |

### YAML Mode

```bash
ORCHID_CONFIG=orchid.yml uvicorn orchid_api.main:app
```

### MD Mode

```bash
ORCHID_CONFIG=orchid.md uvicorn orchid_api.main:app
```

### Hybrid Mode

Keep `orchid.yml` for infrastructure while using `agents/*.md` for agents:

```bash
ORCHID_CONFIG=orchid.yml AGENTS_CONFIG_PATH=agents/ uvicorn orchid_api.main:app
```

---

## Hot-Reload (MD Only)

The on-demand config watcher detects file changes via SHA-256 hashing — no background threads, no fs-notify libraries.

- The `OrchidConfigWatcher` tracks `orchid.md` + `agents/*.md` by their current hashes.
- `Orchid.reload_config()` calls `watcher.reload_if_changed()` and rebuilds the LangGraph when a change is detected.
- Graph rebuild is serialised via `asyncio.Lock` — existing requests complete with the old config.
- The API middleware (`ConfigReloadMiddleware`) polls the watcher at most every `ORCHID_RELOAD_INTERVAL` seconds (default 30, set to 0 to disable).

```bash
# Enable hot-reload with 10-second polling:
ORCHID_RELOAD_INTERVAL=10
```

---

## MD File Format

### `orchid.md` — Root Config

Infrastructure keys (llm, auth, rag, storage) map to environment variables. Agent behavior keys (version, defaults, agents, tools, skills, supervisor, guardrails, events, config_storage, mcp_gateway, external_agents) are validated against the Pydantic schema. The body after the closing `---` is free-form documentation.

### `agents/<name>.md` — Per-Agent Config

Each agent file has YAML frontmatter for structured fields and a Markdown body for the system prompt. The filename stem becomes the agent name.

| Agent MD field | YAML equivalent | Notes |
|---|---|---|
| Frontmatter `description` | `agents.<name>.description` | Short, for supervisor routing |
| MD body | `agents.<name>.prompt` | Rich Markdown, stripped of leading/trailing whitespace |
| Frontmatter `class` | `agents.<name>.class` | Aliased to `class_path` |
| Frontmatter `rag`, `tools`, etc. | `agents.<name>.rag`, etc. | 1:1 mapping |
| Filename `basketball.md` | Dict key `basketball` | Agent name from filename stem |

---

## Equivalence

MD and YAML configs produce identical `OrchidAgentsConfig` output. Run the equivalence test:

```bash
# From the examples repository (orchid-examples)
python md-config/test_equivalence.py
```
