Integrations Reference

Use this page when you need the adapter contract behind settings.integrations: choosing the built-in mock or cli invoker, disabling the live UI, tuning artifact options, or selecting an external adapter. Generated projects start with the mock invoker; switch to cli only when Crewplane should start real provider commands.

For task-oriented setup, use Provider setup, Mock validation, Watch Runs Live and Inspect Results, and Inspecting Run Records.

Need	Integration
Real provider CLI execution	cli invoker
Provider-free testing	mock invoker
Live dashboard	tmux UI
No live UI	none UI
Local run records	filesystem artifacts

These aliases are valid values for settings.integrations.<kind>.implementation:

Kind	Aliases
invoker	cli, mock
ui	tmux, none
artifacts	filesystem

Aliases resolve through the internal registry. An external adapter can also be selected with package.module:ClassName or package.module.ClassName.

Invokers

cli

The cli invoker runs configured provider commands from agents. It owns prompt transport, retries, quota detection, timeout handling, output extraction, and provider usage parsing.

Options: none.

mock

The mock invoker provides deterministic provider-free execution. It writes normal run records without starting provider CLIs.

Options:

• delay_seconds
• observation_delay_seconds
• output_mode
• output_dir
• strict_file_mode
• seed
• fail_when

output_mode is one of lorem, echo, and file. fail_when[] selectors support node_id, task_id, provider, role, audit_round_num, and round_num.

UI

tmux

The tmux UI opens a compact live dashboard when output is a terminal, --no-live is not set, tmux is available, and provider CLI output logging is enabled. Missing tmux degrades to a warning and normal execution.

Options:

• auto_close_session
• tmux_executable
• quiet_after_seconds
• log_tail_lines

none

The none UI disables live observers.

Options: none.

Artifacts

filesystem

The filesystem artifact backend stores stages, results, logs, manifests, preflight bundles, locks, and workspace state under .crewplane/.

Options:

• log_cli_output

Template authorization is configured separately through the core-owned settings.file_access.allowed_template_paths policy.

Real runs currently require the built-in filesystem adapter. External artifact adapters can be used only with crewplane validate and crewplane run --dry-run.

Artifact adapters must provide create_terminal_history_reader() so preflight can resolve terminal results through the selected storage integration. The factory receives the same canonical artifact options used for runtime component construction. The loader rejects adapters that omit this factory.

Extension Contract

Every adapter canonicalization result must have an option_scopes key set that exactly matches its canonical options key set. Scope each option as execution, artifact, observer, or validation; unscoped and unknown entries fail composition. Scopes remain attached to top-level option keys even when their values are nested JSON.

Sensitive option declarations use RFC 6901 JSON Pointers, such as /api_token or /credentials/0/value. Crewplane redacts sensitive values at any depth. All option and capability values must be finite JSON-compatible data.

Observers implement the architecture Observer lifecycle contract and expose one immutable ObserverCapabilities value. Runtime observers receive the architecture ExecutionEvent, DashboardSnapshot, and RunResult contracts. Composition validates capabilities, stop_requested, start, on_snapshot, and stop before a run begins. Persistent required observers and best-effort UI observers express their delivery and cleanup behavior through that capability value rather than dynamic attributes.