Configuration Reference

Config lives at .crewplane/config.yml by default. The version field must match the current SCHEMA_VERSION in src/crewplane/version.py.

For practical setup, start with Provider setup.

Need	Start here
First provider-free run	Generated Mock Config
One real provider	Minimal Config
Full field list	Top Level and agents.<name>
Adapter options	Built-In Integration Options
File-template access	settings.file_access
Workspace isolation	settings.workspace

Minimal Config

Use this as the smallest real-provider config after the provider CLI works in your shell. New crewplane init projects should start with the generated mock config instead.

version: "1.0"
agents:
  codex:
    cli_cmd: ["codex", "exec"]
    provider_kind: "codex"
    prompt_transport: "stdin"
    prompt_transport_arg: "-"

settings:
  integrations:
    invoker:
      implementation: "cli"
      options: {}

This assumes codex --version works directly in your shell and the workflow uses providers: ["codex"].

Generated Mock Config

Generated config from crewplane init starts with one active mock agent and settings.integrations.invoker.implementation: "mock". That makes the first crewplane validate and crewplane run provider-free. Mock output is deterministic scaffolding, not model output.

The generated config also includes commented provider examples for Claude, Codex, Gemini, Copilot, and Kilo. Uncomment and review only the agents you need before switching the invoker to cli.

version: "1.0"

agents:
  mock:
    cli_cmd: ["__crewplane_mock_invoker_never_executes__"]
    provider_kind: "generic"
    prompt_transport: "stdin"
    default_model: "mock"

settings:
  integrations:
    invoker:
      implementation: "mock"
      options:
        output_mode: "lorem"
        seed: 42
        delay_seconds: 0.25
        observation_delay_seconds: 5

Switching To Real Providers

When switching from the generated mock config to real providers:

• keep only the agents entries you want to run
• confirm each provider CLI works directly
• change workflow providers values to those agent names
• set settings.integrations.invoker.implementation: "cli"
• replace generated mock invoker options with options: {}

.crewplane/config.yml defines agents.<name>. Workflows select that same name with providers: ["<name>"]. implementation: "mock" keeps the first run provider-free; implementation: "cli" runs real provider commands.

The following tables are a field index for .crewplane/config.yml; nested settings use dotted paths in the left column.

Top Level

Field	Description
version	Config schema version.
agents	Mapping of provider names to AgentConfig.
settings	Optional runtime settings. If omitted, default settings are used.

agents.<name>

Field	Description
cli_cmd	Non-empty argv list for the provider CLI.
provider_kind	claude, codex, copilot, gemini, kilo, or generic. Defaults to generic.
default_model	Optional model name used when a workflow provider does not override model.
model_arg	CLI flag for model selection when provider_kind: generic. Defaults to --model; can be null. With the built-in cli invoker, do not set it for built-in provider kinds; that invoker ignores it and reports a preflight warning.
prompt_transport	stdin or argv. Defaults to stdin.
prompt_transport_arg	Required for argv; optional stdin sentinel for stdin.
extra_args	Additional argv tokens appended to the provider command.
max_retries	Maximum ordinary non-quota retry attempts. Defaults to 0.
retry_delay_seconds	Delay between generic retries. Defaults to 300.0.
retry_on_exit_codes	Exit codes that trigger retry.
retry_on_stderr_contains	Stderr substrings that trigger retry.
retry_on_output_contains	Combined output substrings that trigger retry.
quota_reached_on_contains	Output substrings treated as quota exhaustion.
quota_reached_retry_delay_seconds	Delay after quota detection. Defaults to 300.0.
quota_reset_sleep_floor_seconds	Minimum sleep when a quota reset time is parsed. Defaults to 5.0.
quota_retry_max_wait_seconds	Optional cumulative quota-wait ceiling for one invocation. Quota retries stop before the next sleep would reach this value.
quota_retry_max_attempts	Optional quota-retry attempt ceiling for one invocation. Quota retries are independent of max_retries.
invocation_timeout_seconds	Optional wall-clock timeout. Defaults to null.
invocation_idle_timeout_seconds	Optional idle-output timeout. Defaults to 1800.0. Gemini's completion-buffered JSON mode cannot enforce it; use invocation_timeout_seconds for a hard limit.
pricing	Optional token pricing buckets.

Command arguments are audited in preflight artifacts, so credentials should normally come from the provider CLI's environment or credential store. If a secret-bearing flag is present in cli_cmd, extra_args, or a workspace setup command, Crewplane replaces split and --flag=value values with an in-memory secret handle before persisting runtime snapshots, plans, setup metadata, diagnostics, or observability records. A keyed fingerprint still participates in execution identity without storing the cleartext value.

agents.<name>.pricing

Pricing values are per million tokens.

Field	Description
input	Input token price.
cached_input	Cached input token price.
cache_write	Cache write token price.
output	Output token price.
reasoning	Reasoning token price.
total	Total token price. Cannot be combined with bucket-specific pricing.

settings

Field	Description
settings.log_level	Runtime log level string. Defaults to info.
settings.sequential_consensus_on_exhaustion	continue or fatal. Defaults to continue.
settings.max_audit_rounds	Maximum allowed node audit_rounds. Defaults to 5.
settings.max_concurrent_nodes	Optional cap on concurrent ready nodes.
settings.max_parallel_invocations	Optional cap on provider invocations inside a parallel node.
settings.file_access	Core file-template authorization policy.
settings.token_budget	Global token budget warning/failure thresholds.
settings.workspace	Experimental workspace isolation settings.
settings.integrations	Adapter implementation and option settings.

settings.file_access

Field	Description
allowed_template_paths	External paths authorized for {{file:...}} templates. Defaults to []. Relative paths resolve from the current working directory; symlinks are resolved before containment checks.

This is a core file-access policy. It applies independently of the selected artifact adapter and participates in workflow signatures. The built-in filesystem adapter rejects allowed_template_paths as an artifact option.

settings.token_budget

Field	Description
settings.token_budget.warn_threshold_chars	Warning threshold for rendered context size. Defaults to 50000.
settings.token_budget.fail_threshold_chars	Optional fail-fast threshold for rendered context size.

settings.workspace

Experimental workspace isolation is disabled by default. Missing settings.workspace is equivalent to settings.workspace.enabled: false. When it is disabled, workflows must not declare worktrees, and provider nodes run from the project root. settings.default_workspace is not supported.

Field	Description
settings.workspace.enabled	Enables Experimental workspace materialization when workflows select worktrees. Defaults to false.
settings.workspace.cache_root	Optional absolute workspace cache path when workspace isolation is enabled. If omitted, Crewplane uses the platform cache location.
settings.workspace.cleanup_on_success	Delete successful workspace cache entries. Defaults to true.
settings.workspace.worktree_contract	blob_exact, the initial fail-closed Git blob-byte contract.
settings.workspace.clean_start	strict or tracked_only. Defaults to strict.
settings.workspace.setup_profiles	Mapping of setup profile names to commands.
settings.workspace.setup_profiles.<name>.run	Non-empty list of argv command lists.
settings.workspace.setup_timeout_seconds	Setup command timeout. Defaults to 600.0.
settings.workspace.identity.include_cache_root	Include cache root in workspace identity. Defaults to false.
settings.workspace.max_concurrent_materializations	Maximum workspace materializations at once. Defaults to 1.
settings.workspace.disk.warn_free_bytes	Optional free-space warning threshold.
settings.workspace.disk.fail_free_bytes	Optional free-space failure threshold. Must not exceed warn_free_bytes.

Prices, delays, timeouts, and other floating-point controls must be finite. YAML infinity and NaN values are rejected, and persisted JSON is emitted in strict RFC-compatible form.

Workspace-enabled runs require a supported ordinary Git repository, POSIX or WSL filesystem behavior, and an invoker adapter that honors runtime-supplied cwd. The initial blob_exact contract rejects Git LFS, custom filters, byte-transforming text/eol attributes, submodules, sparse checkout, and partial clone before provider invocation.

settings.integrations

Field	Description
settings.integrations.invoker.implementation	Invoker alias or dotted path. Defaults to cli.
settings.integrations.invoker.options	JSON-compatible invoker options.
settings.integrations.ui.implementation	UI alias or dotted path. Defaults to tmux.
settings.integrations.ui.options	JSON-compatible UI options.
settings.integrations.artifacts.implementation	Artifact alias or dotted path. Defaults to filesystem.
settings.integrations.artifacts.options	JSON-compatible artifact options.

Built-In Integration Options

cli invoker

Runs configured agents commands against real provider CLIs instead of the deterministic mock invoker. It has no options.

When switching the generated config from mock to cli, replace the generated mock invoker options: block with options: {}. Leaving mock options such as output_mode, seed, or delay settings under the cli invoker is a config error.

Real provider runs start the external commands configured in .crewplane/config.yml. Those tools run with their own filesystem, network, credential, approval, and sandbox settings. Crewplane coordinates them and records artifacts; it does not sandbox them.

mock invoker

Use mock to validate and run workflows without starting provider CLIs. Its output is deterministic scaffolding for orchestration checks, not model output.

Option	Description
delay_seconds	Non-negative delay before mock output. Defaults to 0.
observation_delay_seconds	Non-negative visible-observation delay. Defaults to 5.0.
output_mode	lorem, echo, or file. Defaults to lorem.
output_dir	Fixture directory. Required when output_mode: "file".
strict_file_mode	Fail on missing fixtures instead of fallback output. Defaults to false.
seed	Optional integer seed or null.
fail_when	List of failure selectors.

mock.fail_when[] selector keys are node_id, task_id, provider, role, audit_round_num, and round_num.

The generated mock agent uses a sentinel cli_cmd value. The mock invoker does not start or validate that command.

tmux UI

Option	Description
auto_close_session	Close the tmux session at run end. Defaults to true.
tmux_executable	tmux executable name. Defaults to tmux.
quiet_after_seconds	Quiet-state threshold. Defaults to 120.0; must be at least 1.0.
log_tail_lines	Optional fixed log tail line count from 1 to 200, or null.

none UI

Disables the live UI adapter. Runs still execute normally and write artifacts and logs, but no tmux dashboard or other live observers are created. It has no options.

filesystem artifacts

Option	Description
log_cli_output	Capture provider CLI output logs. Defaults to true.

Dotted-Path Adapters

External adapters can be selected with a dotted path. Their options payload must be finite JSON-compatible data and is validated by the adapter. The canonical result must assign exactly one execution, artifact, observer, or validation signature scope to every canonical option; missing scopes and scopes for unknown options are rejected during adapter wiring. Explicit sensitive option locations must be RFC 6901 JSON Pointers beginning with /.