AI Engines

An engine runs a workflow’s Markdown instructions with its configured tools, sandbox, and safe outputs. This page covers selection and shared configuration. Use the individual references for engine-specific settings.

Built-in AI engines

Engine	Selection	Get started	Technical reference
GitHub Copilot (default)	engine: copilot or omit engine	Copilot setup	Copilot reference
Claude Code	engine: claude	Claude setup	Claude reference
OpenAI Codex	engine: codex	Codex setup	Codex reference
Gemini CLI (deprecated)	engine: gemini	Gemini setup	Gemini reference
Pi	engine: pi	Pi setup	Pi reference
Agy (experimental)	engine: agy	Agy setup	Agy reference

For imported engine definitions and third-party samples, see Custom AI engines. Switching engines may require different credentials, models, tools, and network rules.

Data handling before setup

The engine, inference provider, and enabled tools determine where repository context is processed. Review provider terms, retention, accessible repository content, outbound destinations, and artifact access before enabling a workflow. Credentials and identity mechanisms are documented in Authentication.

Engine Feature Comparison

Feature	Copilot	Claude	Codex	Gemini	Pi	Agy
Top-level max-turns	Yes	Yes	Yes	Yes	Yes	No
max-continuations	Yes	No	No	No	No	No
tools.web-fetch	SDK only	Anthropic only	Yes	Yes	Yes	Cannot disable
Native tools.web-search	No	Anthropic only	Yes	No	No	Cannot disable
Native engine.agent selection	Yes	No	No	No	No	No
engine.api-target	Yes	Yes	Yes	Yes	Yes	No
engine.bare	Yes	Yes	No	No	Yes	No
Custom engine.harness	Yes	Yes	Yes	No	No	No
Per-command bash allowlist	Yes	Yes	No	Yes	Yes	No
Native MCP	Yes	Yes	Yes	Yes	Yes	Production-conformance gated
Agent Plugins (plugins)	Yes	Yes	Yes	No	No	No
Artifact-backed engine.durable	Session (CLI/SDK)	Session	Session	Session	Session (CLI/SDK/RPC)	Session

Codex can disable shell execution but cannot enforce a command allowlist. Agy rejects unsupported tool restrictions rather than ignoring them. See individual references for provider-specific web access, bare-mode behavior, and dynamic workflows.

max-turns defaults to 500 (legacy alias max-runs); max-ai-credits defaults to 1000. These are top-level fields, not engine properties. Agy supports credit/cache-miss limits but not max-turns. engine.max-turns is a deprecated Claude-only iteration limit. Agent Plugins remain experimental.

Extended Coding Agent Configuration

String form selects a built-in engine. Object form adds settings:

engine:
  id: copilot
  model: opus
  env:
    DEBUG_MODE: "true"

Field	Contract
id	Built-in ID, or the ID of an imported definition.
model	Exact model ID, alias, or provider-prefixed selection; may also be top-level model.
version	Override the compiler-pinned CLI version.
cooldown	Minimum release age in nonnegative integer days; defaults to 3. Explicit 0 is rejected in strict mode.
env	Runtime environment values; scope and precedence still apply.
args	Ordered arguments passed to the native CLI before its prompt argument.
command	Replacement executable; skips the engine installer, not AWF installation.
api-target	Endpoint hostname, where supported; see below.
harness	Replacement wrapper or retry settings for Copilot, Claude, and Codex.
durable	Artifact-backed session continuation with optional retention-days (1–90, default 7).

Engine-specific options such as agent, copilot-sdk, driver, dynamic-workflows, permission-mode, config, and extensions are documented in each engine reference. Agy rejects most overrides.

Durable runs

Caution

Durable mode is experimental for all engines, including Pi. Enabling engine.durable emits a compile-time warning. Configuration and behavior may change without deprecation.

All built-in engines support artifact-backed continuation:

engine:
  id: copilot
  durable:
    retention-days: 7

The compiler restores an explicit parent from aw_context, or the last successful run of the same workflow on the same branch. Reruns prefer a checkpoint from an earlier attempt of the same run. Retention remains subject to repository and organization policy. No memory tool is required, and durable mode does not dispatch another run automatically.

Engine	Persisted state	Continuation
Copilot CLI and SDK	Native session-state files and exact session ID	CLI --session-id; SDK resumeSession
Claude	Project transcripts, task state, and exact session ID	CLI --resume <id>
Codex	Native and archived rollout sessions and exact thread ID	CLI exec resume <id>
Gemini	Native temporary session storage and project registry	Prompt points to restored session files
Agy	Native conversation databases	Prompt points to restored session files
Pi CLI, SDK and RPC	Native JSONL conversation session	CLI/RPC --session; SDK SessionManager.open

Copilot, Claude, Codex, and Pi resume the exact recorded native session with the current workflow prompt and freshly configured credentials, models, and tool policy. Gemini and Agy receive restoration metadata without a forced CLI continuation argument. Continuation guidance limits use to metadata unless historical facts are independently verified against trusted sources for the current task. It does not direct the agent to ingest restored text as prompts or instructions.

Enabling engine.durable opts into reusing potentially attacker-influenced history across runs. Guidance to treat restored files as untrusted factual data is advisory, not deterministic instruction/data isolation; native session resume also reintroduces prior history. Durable continuation does not eliminate cross-run prompt injection.

The first run creates a new session when no prior run or implicit checkpoint exists. No continuation notice is added without history. Missing explicit-parent artifacts, corrupt restored sessions, and API authorization failures remain errors rather than silently starting unrelated conversations.

This restores session files, not workspace edits, credentials, pending task phases, or exactly-once tool execution. Existing unified session capture and trace propagation remain enabled; restored Copilot events are excluded from current-run capture and model verification.

The unified session records durable.restore with restored, fresh, or failed status and available parent-run and artifact IDs. Copilot, Claude, Codex, and Pi additionally record durable.session after native session startup, with resumed or fresh status and the selected session ID. These records contain metadata, not historical conversation content. Restoration alone does not establish native continuation for Gemini, Agy, or imported engines.

Metadata recording and collection are best effort: failures emit warnings without changing restoration or native startup outcomes. Missing records leave continuation evidence unavailable; they do not establish a fresh start or a failed restore.

gh aw audit RUN --artifacts info,usage --json exposes this evidence as durable_session. gh aw health WORKFLOW --json --logs-dir DIRECTORY summarizes cached current-revision evidence under durable_sessions, without downloading artifacts. Missing historical events or uncached sessions are unavailable evidence, not fresh starts. An Actions success does not by itself verify continuation.

OpenTelemetry agent spans and exported durable session log records expose the validated checkpoint parent as the string attribute gh-aw.durable.parent_run_id, including Pi native sessions. This identifies the parent Actions run; it does not replace OTel trace/span parentage or prove native startup by itself. Fresh runs omit the attribute.

Threat detection uses a separate fresh session and does not inherit the primary agent’s durable state.

Built-in session-based durable mode rejects replacement commands, custom drivers, and harnesses because their session files may differ. Pi’s built-in SDK and RPC drivers remain supported. Ordinary CLI arguments remain supported, but native session selectors and flags that disable persistence cannot override compiler-managed continuation. Copilot cannot override COPILOT_HOME because durable mode collects its standard native session directory. Pi has additional restrictions. Imported engines must declare their own durable files and execution behavior; unsupported definitions still fail compilation.

Checkpoint artifacts are published after secret redaction and integrity validation. Cancellation or hard runner loss can prevent publication; only the last published checkpoint can be restored.

Artifacts contain restorable session content, not just integrity metadata, and may expose sensitive history to anyone with artifact access. Secret scanning and redaction are heuristic: they do not guarantee removal of PII, unknown token formats, or secrets in unsupported encodings. Enable durable mode only when the workflow’s session content is suitable for the repository’s artifact access and retention policies.

Pinning a Specific Engine Version

The compiler pins a CLI release. Override it with engine.version, then recompile:

engine:
  id: copilot
  version: "1.0.101"

Versions can use GitHub Actions expressions; the runtime passes them through environment variables rather than shell interpolation. Copilot expression values must resolve to trusted cached releases or built-in manifest pins. Other Copilot releases require a literal version and checksum pin. Agy accepts only its verified releases.

Engine release-age cooldown

Compiler-managed engine installs require releases to be at least 3 days old by default. Configure a different age with engine.cooldown:

engine:
  id: copilot
  cooldown: 7

The value must be a nonnegative integer number of days, not a boolean, string, duration, or expression. cooldown: 0 disables the age check only when strict: false; strict mode rejects explicit zero. Omitting the field retains the default, including string-form and inline engine configurations.

Claude, Codex, Pi, Gemini, and behavior-defined npm installs pass this age to npm through NPM_CONFIG_MIN_RELEASE_AGE, including compiler-managed microVM staging. Copilot’s native installer checks GitHub release publication metadata before activating a cached CLI or downloading an archive, including musl guest binaries. Missing or invalid metadata fails the installation. The cooldown also applies to pinned versions and runtime version expressions; it does not replace checksum verification or version pins.

npm enforces the cooldown through its built-in min-release-age setting at installation time; no custom version-check script is generated. Node.js runtime overrides must provide npm 11.10.0 or later to support this setting. Older npm versions may ignore it.

The policy covers compiler-managed npm and Copilot release installs, not arbitrary shell installers, custom engine.command executables, pre-agent steps, extensions, or other externally managed installation methods. Runtime dependency cooldowns remain separately configured by runtimes.<id>.cooldown (a boolean).

Engine definitions that set behaviors.installation.cooldown use deprecated metadata that is ignored. Set engine.cooldown in the workflow instead. A value of 0 disables the policy only outside strict mode; strict mode rejects zero.

Engine Environment Variables

Use engine.env for engine-only runtime values. Use top-level env for all workflow steps; see environment variable scope and precedence.

Enterprise API Endpoint (api-target)

api-target is a hostname, without protocol or path, and must be permitted by network.allowed:

engine:
  id: copilot
  api-target: api.acme.ghe.com
network:
  allowed: [defaults, acme.ghe.com, api.acme.ghe.com]

For GHES Copilot use api.enterprise.githubcopilot.com. See GHE Cloud troubleshooting for data-residency setup. Agy does not support api-target.

Custom API Endpoints via Environment Variables

Engine	Base URL variable
Copilot	GITHUB_COPILOT_BASE_URL
Claude	ANTHROPIC_BASE_URL
Codex	OPENAI_BASE_URL
Gemini	GEMINI_API_BASE_URL

Set the URL through engine.env and allow its domain in network.allowed. AWF derives the proxy target from it. Copilot’s api-target takes precedence over GITHUB_COPILOT_BASE_URL. Pi’s additional provider routing is in its reference.

For OPENAI_BASE_URL and ANTHROPIC_BASE_URL, gh-aw disables automatic model fallback by default so provider-specific model IDs pass through unchanged. Explicit sandbox.agent.model-fallback overrides that default. If proxy-side model steering is incompatible with the endpoint, use sandbox.agent.token-steering: false.

Engine Command-Line Arguments

engine.args is an ordered array of native CLI arguments, inserted before the prompt argument. Consult the selected CLI’s documentation for available flags; Agy rejects this setting.

Custom Engine Command

engine.command replaces the executable and skips the engine installer, not AWF installation. Provision it in setup steps and ensure it satisfies the selected engine’s version/configuration contract. Agy checks the verified executable version; Copilot checksum pins cannot be combined with command.

Custom Harness Script (harness)

Copilot, Claude, and Codex accept a replacement harness provisioned in ${RUNNER_TEMP}/gh-aw/actions/, for example through pre-agent-steps:

engine:
  id: copilot
  harness:
    use: custom_copilot_harness.cjs

use must start with a letter, digit, or underscore, end in .js, .cjs, or .mjs, and contain no directory separators, .., or shell metacharacters. Selecting it does not copy a repository file. Node 24 is provisioned automatically. A replacement owns its retry, timeout, prompt-delivery, and tool-policy behavior.

Harness Retry and Post-result Watchdog Policy

The built-in Copilot, Claude, and Codex harnesses accept:

engine.harness field	Default	Meaning
max-retries	3	Retries after the initial attempt; 0 disables.
initial-delay-ms	5000	First retry delay.
backoff-multiplier	2	Exponential delay multiplier.
max-delay-ms	60000	Delay cap.
watchdog-timeout	120	Post-result idle timeout; literal integers are seconds.

All accept integers or Actions expressions. A watchdog expression must already be in milliseconds. Explicit engine.env.GH_AW_HARNESS_* values override these fields; see runtime tuning variables.

The watchdog arms after a terminal safe output, not diagnostic reports such as report_incomplete. Any stdout/stderr activity resets it. It can terminate a quiet process still doing useful work and treat that termination as success if a terminal output exists. Claude counts only terminal outputs from the current attempt; its resume rules also apply.

Threat detection defaults to zero retries; configure its engine explicitly to change that. Model fallback below retries individual inference requests, not whole agent attempts.

Model aliases

Note

The Copilot model catalog offered to a workflow can differ by organization and lag the models available to that organization’s Copilot seats. Availability depends on the agentic-workflows integration, not just organization policy; a model listed by this repository’s daily inventory is not necessarily offered to another workflow. An exact Copilot ID missing from a complete live catalog means that model is not offered to this workflow. Prefer aliases such as opus and sonnet over exact Copilot IDs so resolution selects an available model. Run gh aw audit <run-url> --models for a detailed report of that run’s model information, including its catalog, discovery status, supported endpoints, and recorded routing and usage. Missing or incomplete discovery does not confirm model absence.

Copilot, Claude, Codex, Pi, and Agy resolve aliases against the configured provider’s live AWF /reflect catalog before execution:

• Built-in aliases such as opus/small, workflow-defined models:, and their globs select the newest live match.
• A provider/ prefix restricts the lookup; otherwise the engine’s configured provider applies.
• Exact live IDs take precedence over an alias of the same name. Unrecognized exact IDs are not rewritten by alias resolution. Pi checks exact IDs before launch; Copilot, Claude, and Codex fail on the first unavailable-model request.
• Parameters such as ?effort= are retained. auto keeps its engine/provider-specific meaning.
• Missing alias matches fail with model_unavailable; incomplete discovery fails alias resolution with catalog_unavailable.

Gemini and declarative engines pass model names through unchanged and warn about gh-aw aliases. AWF can independently rewrite unrecognized models on non-Copilot providers; disable sandbox.agent.model-fallback when exact routing is required.

Resolution produces model.resolution evidence in usage/aw_session.jsonl. See Model Aliases for the catalog and Model Routing for experimental per-run model/effort selection on Copilot-backed Copilot, Claude, Codex, and Pi.

Ordered model fallback (fallback-models)

engine:
  id: copilot
  model: grok-4.7
  fallback-models: [gpt-5.6-luna, mai-code-1.1-flash]

All built-in engines accept ordered, concrete same-provider alternatives with AWF v0.28.31+ and a compatible API-proxy image. AWF retries the failed request without restarting the agent, preserving policy and budget checks. An explicit chain disables automatic middle-power substitution.

Fallback covers server errors, request timeouts, unsupported models, and model-availability HTTP 400 errors. Authentication failures, HTTP 429, policy/guardrail failures, cancellation, and job timeouts do not switch models. Exhausted chains fail the run.

Unqualified alternatives inherit the primary provider. Prefixes must match it; credentials follow that provider’s normal configuration. Cross-provider chains, fallback aliases, missing compatible AWF, and combinations with engine.model-routing fail compilation. Custom harnesses/drivers can use AWF fallback without implementing switching.

token-usage.jsonl records the serving model and model_fallback evidence for post-run attribution. This does not change harness retries or prove that every configured alternative was exercised.

Bare Mode (bare)

engine.bare: true disables ambient discovery in Copilot, Claude, and Pi; default false. Copilot suppresses custom instructions. Claude skips ambient discovery but keeps explicitly installed workflow skills/plugins, with a minimal native tool set. Pi retains managed infrastructure and explicitly loaded workflow skills. See individual references for delegation and dynamic-workflow restrictions.

Timeout Configuration

Setting	Default	Scope
timeout-minutes	20	Entire agent job.
tools.timeout	60 seconds for Claude/Codex	Supported tool operations; Codex native MCP calls, not shell commands.
tools.startup-timeout	120 seconds for Codex	MCP server startup; explicit Codex server config takes precedence.
max-turns	500	AWF invocation cap, except unsupported Agy.
max-continuations	Unset	Copilot autopilot continuation budget.

Claude receives top-level max-turns automatically; no duplicate CLAUDE_CODE_MAX_TURNS is needed. Copilot and Gemini retain native tool-limit behavior. See tool timeouts and long builds.

Configuration conformance workflows

Repository engine-conformance-<id>.md workflows are manual configuration smoke tests. They check file/shell/MCP probes and typed results using recorded receipts, not an agent’s success claim. Safe outputs are staged; missing credentials fail activation. Reports are retained for two days.

These tests do not establish security, model quality, SDK/driver coverage, or provider compliance with a requested model. Agy’s production gate is separate from its native authentication probe.

Engine-specific sections

The following anchors retain links to sections moved from this page.

Copilot Custom Configuration

See Copilot custom agents.

Copilot release checksum pins

See Copilot release integrity.

Copilot Bring Your Own Key (BYOK) Mode

See Copilot BYOK.

Copilot SDK Support

See Copilot SDK configuration.

Pi Extensions (extensions)

See Pi packages.

Claude Tool Enforcement Security Model

See Claude permissions and gateway enforcement.

Shared imported engines

See Custom AI engines.

Unsupported engine samples

See third-party samples, including the experimental Atomic and mini-SWE-agent declarative engines.