Configuration reference

Configuration is not one file in Orcho. It is a layered policy surface: local runtime settings, profile shape, project tuning, prompt parts, skills, worker runtimes, and control clients all contribute to a run.

Use this page when you already understand the basic lifecycle and need to answer expert questions:

• Which runtime and model handles each phase?
• Will the worker edit in a run-owned checkout or directly in the project?
• Does implementation run as one worker call or as a tracked subtask DAG?
• When does Orcho pause for human feedback?
• Which gates are advisory, required, or terminal?
• Where should a project-specific rule live?

Read config top-down

Start from the broadest question and only then move to exact keys.

Question	Primary surface
What kind of work is this?	profile: small_task, feature, planning, code_review, refactor, and related work kinds
How strict should the run be?	operating mode and profile default mode
Where will the worker edit?	worktree.*, profile worktree_isolation, CLI isolation override
How will implementation execute?	profile or pipeline.implementation_execution
Which worker runtime handles each phase?	phases.<phase>.runtime, phases.<phase>.model, RUNTIME_<PHASE>, MODEL_<PHASE>
What project facts and checks should Orcho know?	project plugin and verification gates
Which prompt behavior changes?	prompt role/task/format overrides
Which specialist procedures are trusted?	skill registry and project/workspace skill trust
How is the run controlled from a client?	CLI flags, MCP tools, events, artifacts

Local config layers

The normal local overlay chain is:

environment variables
  > $ORCHO_WORKSPACE/.orcho/config.local.json
  > ~/.orcho/config.local.json
  > _config/config.local.json
  > _config/config.defaults.json

Use the workspace file for a project group:

workspace-orchestrator/.orcho/config.local.json

Use the user file for machine-wide defaults:

~/.orcho/config.local.json

Use the package-local file only for quick development overrides:

_config/config.local.json

Disable all local JSON layers for a deterministic run:

ORCHO_DISABLE_LOCAL_CONFIG=1 orcho run --project ./my-project --task "..."

Runtime and model routing

Phase routing is the first expert knob. Each phase can use its own worker runtime, model, and effort level.

{
  "phases": {
    "plan": {
      "runtime": "claude",
      "model": "claude-opus-4-8[1m]",
      "effort": "high"
    },
    "review_changes": {
      "runtime": "codex",
      "model": "gpt-5.5",
      "effort": "medium"
    },
    "final_acceptance": {
      "runtime": "codex",
      "model": "gpt-5.5",
      "effort": "low"
    }
  }
}

The canonical environment override shape is:

RUNTIME_<PHASE>
MODEL_<PHASE>

Phase	Runtime env	Model env
plan	RUNTIME_PLAN	MODEL_PLAN
validate_plan	RUNTIME_VALIDATE_PLAN	MODEL_VALIDATE_PLAN
implement	RUNTIME_IMPLEMENT	MODEL_IMPLEMENT
review_changes	RUNTIME_REVIEW_CHANGES	MODEL_REVIEW_CHANGES
repair_changes	RUNTIME_REPAIR_CHANGES	MODEL_REPAIR_CHANGES
repair_escalation	RUNTIME_REPAIR_ESCALATION	MODEL_REPAIR_ESCALATION
final_acceptance	RUNTIME_FINAL_ACCEPTANCE	MODEL_FINAL_ACCEPTANCE

CODEX_MODEL can act as a fallback for MODEL_REVIEW_CHANGES when the more specific variable is not set.

Execution policy

Do not confuse phase execution with implementation delivery.

Setting	Values	Meaning
steps[].execution.mode	linear	How a profile step is invoked. Shipped profiles use linear steps.
pipeline.implementation_execution	whole_plan, subtask_dag	How the built-in implement phase consumes a parsed plan.
profile implementation_execution	whole_plan, subtask_dag	Profile-level override for implementation delivery.

subtask_dag is sequential today. It tracks subtasks as delivery units, but it does not imply parallel execution.

{
  "pipeline": {
    "implementation_execution": "whole_plan"
  }
}

Profiles such as feature and refactor can choose subtask_dag directly, so the profile can override the pipeline default.

Session policy

Session config controls when Orcho lets a runtime continue context across implementation and repair.

Setting	Meaning
session.mode	auto, stateless, chain, or hybrid policy for session continuation.
session.chain_same_model_only	Prevents chain continuation across different models.
session.auto_chain_max_tokens_in	Upper input-token budget for automatic chaining.
session.auto_chain_max_tool_calls	Upper tool-call budget for automatic chaining.

Profile steps also declare session boundaries:

Profile step key	Meaning
execution.session_split	stateless, per_phase, per_role, or common separation across phases.
execution.session_continuity	fresh_only, loop_continue, or same_zone_continue behavior across repeated calls.

Use pipeline.session_split_override when a workspace must override a shipped profile without forking the whole profile.

{
  "pipeline": {
    "session_split_override": {
      "review_changes": "per_phase"
    }
  }
}

The environment form is also supported:

ORCHO_SESSION_SPLIT_OVERRIDE='review_changes=per_phase' orcho run ...

Isolation policy

Orcho separates the target project from the checkout used by one run.

Concept	Meaning
{project}	Durable target repository.
{checkout}	The checkout the worker sees: either a run-owned worktree or the project checkout itself.

Global config:

{
  "worktree": {
    "enabled": true,
    "isolation": "per_run",
    "retention_days": 7,
    "allow_destructive_inside": true
  }
}

Resolution order for isolation is specific:

CLI override
  > profile worktree_isolation
  > worktree config

Focused profiles such as planning, research, delivery_audit, and code_review can run with worktree_isolation: "off" because they inspect the current checkout or produce a plan only. Full delivery profiles normally keep per-run isolation.

Pre-run dirty intake is a separate policy:

{
  "pre_run_dirty": {
    "enabled": true,
    "interactive_default": "include",
    "non_interactive_default": "halt",
    "include_untracked": "prompt"
  }
}

When isolation is on and the project checkout is dirty, Orcho can ask whether to include, exclude, commit, or halt before it starts the run-owned checkout.

Profile policy

Profiles are executable configuration. They decide phase graph, loops, handoffs, prompt parts, gates, cross projection, and some delivery defaults.

Key	Meaning
semantic_profile	Work-kind identity, for example feature or planning.
default_mode	Default strictness posture such as fast or pro.
recipe_kind	Broad recipe family: full cycle, focused, or internal.
implementation_execution	Optional profile-level implement delivery policy.
worktree_isolation	Optional profile-level isolation intent.
steps	Phase graph, loops, prompts, gates, handoffs, and cross projection.
cross_gates	Cross-run terminal gates such as contract check and system release gate.

Built-in profile orientation:

Profile	Default mode	Implementation	Isolation intent	Cross terminal gates
small_task	fast	pipeline default	off	no
feature	fast	subtask_dag	global default	yes
complex_feature	pro	pipeline default	global default	yes
planning	pro	none	off	no
research	fast	none	off	no
delivery_audit	pro	none	off	no
code_review	pro	none	off	no
refactor	pro	subtask_dag	global default	yes
migration	pro	pipeline default	global default	yes

Internal profiles such as task and correction exist for scoped follow-up flows. Treat them as advanced lifecycle machinery, not beginner profile choices.

Profile overlays

Local config can patch shipped profiles without copying the full profile JSON.

{
  "profiles_v2": {
    "feature": {
      "_profile": {
        "worktree_isolation": "off"
      },
      "review_changes": {
        "handoff": {
          "type": "human_feedback_always"
        }
      }
    }
  }
}

Rule	Meaning
_profile	Deep-merges into the top-level profile object.
phase name	Deep-merges into the matching phase step.
one phase match required	If the phase is absent or ambiguous, loading fails.
lists are replaced	To append a list such as quality_gates, restate the full list.

Use overlays for local policy, not for hiding unclear task requirements. If a workflow becomes broadly reusable, author a proper profile.

Handoff policy

Handoffs are first-class profile policy.

Handoff type	Behavior
human_bypass	The run does not pause for the human at that step.
human_feedback_on_reject	Pause only when automatic rounds are exhausted and the gate is still rejected or incomplete.
human_feedback_always	Pause on every round so the human decides continue, retry with feedback, or halt.

For subtask_dag implementation, an implement handoff can also carry:

Key	Meaning
repair_attempts	Automatic substance-repair budget before a handoff or fallback.
on_exhausted	What to do when the repair budget is spent.

Read this together with Handoffs and advisors.

Verification and quality gates

Quality gates can appear inside profile steps, while verification receipts prove what actually ran.

Profile step shape:

{
  "phase": "implement",
  "quality_gates": [
    {
      "name": "tests",
      "kind": "computational",
      "on_fail": "feed_into_next",
      "feed_target": "last_test_output"
    }
  ]
}

Read the two surfaces separately:

Surface	Purpose
quality_gates on a profile step	Phase-local check or feedback policy.
project plugin gates	Project-specific commands and test policy.
verification receipts	Durable proof that a command ran in the expected checkout/environment.
final acceptance	Release gate that interprets findings, receipts, and remaining gaps.

The live CLI verification header can expose gate name, timing, run mode, policy level, and cost kind. The policy tier matters:

Policy	Meaning
require	Missing or failed required evidence can block delivery.
warn	Surface the gap, but do not treat it as the same as a required blocker.
suggest	Operator-run or advisory verification.

Use Verification receipts for the proof model and Profiles and gates for the workflow policy model.

Auto-detect policy

--profile auto-detect is a selector. It recommends a concrete profile and mode before normal profile dispatch.

{
  "pipeline": {
    "auto_detect": {
      "policy": "confirm",
      "confidence_threshold": 0.7,
      "fallback_profile": "feature",
      "on_low_confidence": "fallback",
      "on_error": "fallback",
      "topology_signals": {
        "mcp schema": ["orcho-core", "orcho-mcp"],
        "wire format": ["orcho-core", "orcho-mcp"]
      }
    }
  }
}

Surface	Role
concrete profile	Executable run shape.
auto-detect	Recommendation step before dispatch.
topology signals	Heuristic advice about participant sets or cross shape.

Non-interactive policy

--no-interactive is not one config key. It is the absence of prompts across several policy surfaces.

Surface	Relevant policy
Fresh run shape	Pass --profile, or configure trusted auto-detect threshold and fallback behavior.
Pre-run dirty checkout	pre_run_dirty.non_interactive_default decides include, exclude, commit, or halt.
Phase handoff retry	Non-interactive runs can use the bounded CI advice path for eligible retry_feedback cases.
Required verification	Required missing or failed receipts block delivery.
Delivery decision	commit.auto_in_ci decides unattended delivery when the release and verification gates allow it.
Cost visibility	accounting.enabled records API-equivalent cost when you need CI workload economics.

Read CI autopilot before treating these as a single switch. A tuned project can give Orcho high autonomy; an untuned project should stop instead of guessing.

Delivery and artifacts

Post-run delivery is governed separately from run execution.

Setting	Meaning
commit.enabled	Enables post-release delivery handling.
commit.default_strategy	Commit message or release-summary strategy.
commit.interactive_default	Preselected interactive delivery action.
commit.auto_in_ci	Unattended delivery action.
commit.decision_mode	Whether unattended delivery acts immediately or can defer the decision.
commit.add_untracked	Whether non-ignored untracked files can be staged by delivery actions.
commit.include_pre_existing_dirty	Reserved guard for pre-existing dirty state.
commit.git_user_identity	Optional git identity override.

Artifact mirroring is separate:

{
  "artifacts": {
    "mirror_to_project": false,
    "mirror_patterns": ["plan.md", "todo.md", "review.md", "diff.patch"],
    "mirror_dir": ".orcho/artifacts"
  }
}

Use ARTIFACTS_MIRROR=1 for the environment override.

Accounting and output

Accounting is opt-in:

{
  "accounting": {
    "enabled": true
  }
}

or:

ORCHO_ACCOUNTING=1

CLI output mode can be configured when no command-line output flag is passed:

{
  "cli": {
    "output_mode": "live"
  }
}

or:

ORCHO_OUTPUT_MODE=debug

Valid output modes are summary, live, and debug.

Language and timeouts

Natural-language artifact defaults:

{
  "language": {
    "plan_language": "English",
    "task_language": "English"
  }
}

Environment overrides:

PLAN_LANGUAGE
TASK_LANGUAGE

Timeouts have two shapes:

Setting family	Meaning
<runtime>_seconds	Hard wall-clock cap. 0 means off.
<runtime>_idle_seconds	Idle watchdog. The timer resets when the worker streams output.

Configured runtime families:

claude_seconds, claude_idle_seconds
codex_seconds, codex_idle_seconds
gemini_seconds, gemini_idle_seconds

Environment equivalents include CLAUDE_TIMEOUT, CODEX_TIMEOUT, GEMINI_TIMEOUT, CLAUDE_IDLE_TIMEOUT, CODEX_IDLE_TIMEOUT, and GEMINI_IDLE_TIMEOUT.

Sandbox and process hygiene

Launch-layer sandbox config is not a replacement for the worker runtime’s own approval and filesystem policy. It controls Orcho-side environment hygiene, resource limits, masking, and child-process cleanup.

Setting	Meaning
sandbox.mode	env by default, or off to disable this layer.
sandbox.env_allowlist	Additional environment variables allowed into worker processes.
sandbox.env_denylist	Variables that must be withheld. Denylist wins.
sandbox.limits.cpu_seconds	CPU limit, 0 for no configured limit.
sandbox.limits.memory_mb	Memory limit, 0 for no configured limit.
sandbox.limits.open_files	File descriptor limit, 0 for no configured limit.
sandbox.limits.file_size_mb	File-size limit, 0 for no configured limit.
sandbox.masking.builtin_patterns	Built-in token-pattern masking.
sandbox.masking.custom_patterns	Additional masking patterns.

Project tuning and prompt config

Not every setting belongs in config.local.json.

Need	Put it here
Project name, stack, architecture, path hints	project/.orcho/multiagent/plugin.py
Project test commands and review focus	project plugin quality_gates, build hints, review hints
Same prompt posture across a workspace	workspace-orchestrator/.orcho/multiagent/prompts/
Project-specific role, task, or format behavior	project/.orcho/multiagent/prompts/
Reusable specialist procedure	.agents/skills/<skill>/SKILL.md
Phase order, loops, handoffs, cross gates	profile policy
Runtime/model assignment	phases.*, RUNTIME_<PHASE>, MODEL_<PHASE>

Prompt resolution order:

project prompt override
  > workspace prompt override
  > core prompt default

Read Project tuning and plugins, Prompt engine, and Skill registry before using prompt overrides as the first tool.

Source-backed setting map

This is the compact map of the current core config surface.

Section	Keys
phases	plan, validate_plan, implement, review_changes, repair_changes, repair_escalation, final_acceptance
phases.<phase>	runtime, model, effort
timeouts	claude_seconds, codex_seconds, gemini_seconds, claude_idle_seconds, codex_idle_seconds, gemini_idle_seconds
session	mode, chain_same_model_only, auto_chain_max_tokens_in, auto_chain_max_tool_calls
codemap	enabled, languages, max_depth
hypothesis	enabled, max_attempts
pipeline	change_handoff, implementation_execution, session_split_override, auto_detect
pipeline.auto_detect	policy, confidence_threshold, fallback_profile, on_low_confidence, on_error, topology_signals
cli	output_mode
accounting	enabled
commit	enabled, default_strategy, interactive_default, auto_in_ci, decision_mode, add_untracked, include_pre_existing_dirty, git_user_identity
language	plan_language, task_language
artifacts	mirror_to_project, mirror_patterns, mirror_dir
worktree	enabled, isolation, retention_days, allow_destructive_inside
pre_run_dirty	enabled, interactive_default, non_interactive_default, include_untracked
sandbox	mode, env_allowlist, env_denylist, limits, masking

Expert checklist

Before changing config, answer these in order:

1. Is this a one-off task decision, a project policy, or a reusable profile?
2. Should the run start from a clean run-owned checkout or current project state?
3. Which profile and mode express the risk level?
4. Does implementation need whole_plan or subtask_dag?
5. Which phases need stronger or cheaper runtimes?
6. Which gates must block delivery, and which only record evidence?
7. Should a rejection pause for human correction or auto-spend another round?
8. Does the rule belong in config, plugin, prompt override, skill, or code?
9. Can the chosen config be explained from live output and artifacts after the run?

Related

• Profile semantics explains the beginner mental model.
• Profile advisor explains --profile auto-detect.
• Profile reference lists profile modes and schema settings.
• Profiles and gates explains policy shape.
• Project tuning and plugins explains project facts and quality gates.
• Plan contract and DAG explains implement execution policy.
• Runtime adapters explains worker runtime routing.