Pilot

Executors

Pilot executor reference — Browser, Terraform, Git, Persist, Shell, HTTP, and Composite.

HTML Markdown JSON

Executors

Pilot routes each playbook step to an executor based on the step’s executor field or its action prefix. The executor registry resolves the target executor in this order:

  1. Explicit executor field on the step
  2. Action prefix inference (tf_ -> terraform, git_ -> git, etc.)
  3. Default: browser

Browser (default)

The browser executor drives a Playwright browser instance. It handles all 14 built-in actions: navigate, click, fill, select, set_toggle, wait_for, assert, capture, capture_secret, ai_decide, scroll, hover, press, upload.

When ai_fallback: true, a failing selector triggers the AI healing engine, which compares the stored DOM snapshot to the current page and proposes a replacement selector.

Configuration

No explicit configuration required. The browser executor starts automatically.

Env varPurposeDefault
CUITTY_AI_KEYAI model key for selector healing(local model)

Terraform

Wraps the Architect API for infrastructure provisioning. Steps are prefixed with tf_.

ActionDescriptionKey fields
tf_initCreate or ensure a targettarget_id, provider, kind
tf_validateValidate target configtarget_id, resource_types
tf_planGenerate a runtime plantarget_id, resource_types
tf_applyApply runtime statetarget_id, resource_types
tf_destroyDestroy runtime resourcestarget_id, resource_types
tf_outputRead a specific output valuetarget_id, output_name
tf_importImport an existing resourcetarget_id, resource_type, resource_id
tf_stateRead full runtime statetarget_id

All Terraform steps accept an optional capture_as field and allow_remote boolean.

Configuration

Env varPurposeDefault
PILOT_ARCHITECT_URLArchitect API base URLhttp://localhost:4470
PILOT_EXECUTOR_TERRAFORMEnable/disabletrue

Git

Wraps the Code API for repository and pull request operations. Steps are prefixed with git_.

ActionDescriptionKey fields
git_cloneCreate a repositoryname, visibility, auto_init
git_branchCreate a branchowner, repo, name, sha
git_commitCreate a commitowner, repo, message
git_pushPush a branchowner, repo, branch
git_pr_createOpen a pull requestowner, repo, title, head, base
git_pr_mergeMerge a pull requestowner, repo, number, strategy
git_tagCreate a tagowner, repo, tag_name, name
git_releaseCreate a releaseowner, repo, tag_name, name, body

Merge strategies: merge, squash, rebase, fast_forward.

Configuration

Env varPurposeDefault
PILOT_CODE_URLCode API base URLhttp://localhost:4351
PILOT_EXECUTOR_GITEnable/disabletrue

Persist

Wraps the Persist API for storage provisioning and data management. Steps are prefixed with persist_.

ActionDescriptionKey fields
persist_provisionProvision storage storesprofile, stores
persist_migrateRun database migrationsdry_run
persist_syncSync data between stores
persist_backupCreate a backup
persist_restoreRestore from backuparchive_path
persist_proxy_startStart the proxy
persist_proxy_stopStop the proxy

Configuration

Env varPurposeDefault
PILOT_PERSIST_URLPersist API base URLhttp://localhost:4290
PILOT_EXECUTOR_PERSISTEnable/disabletrue

Shell

Executes shell commands with an allowlist for security. Steps are prefixed with shell_.

ActionDescriptionKey fields
shell_execRun a single commandcommand, args, env
shell_scriptRun a multi-line scriptcommand
shell_assertRun a command and assert outputcommand, assert

Shell assertions support: exit_code, stdout_contains, stderr_empty.

Configuration

Env varPurposeDefault
PILOT_EXECUTOR_SHELLEnable/disablefalse (disabled by default)

The shell executor uses an allowedCommands allowlist in executor_config:

executor_config:
  shell:
    allowedCommands: ["curl", "dig", "nslookup", "jq"]
    timeout: 30000

HTTP

Makes API requests, polls endpoints, and asserts response contents. Steps are prefixed with http_.

ActionDescriptionKey fields
http_requestSend an HTTP requesturl, method, headers, body
http_assertRequest + assert responseurl, assert
http_pollPoll until condition meturl, until, interval, max_attempts

HTTP assertions support: status, body_contains, header.

Configuration

Env varPurposeDefault
PILOT_EXECUTOR_HTTPEnable/disabletrue

The HTTP executor supports an allowedHosts restriction in executor_config:

executor_config:
  http:
    allowedHosts: ["api.cloudflare.com", "api.github.com"]
    timeout: 30000

Composite

The composite executor orchestrates other steps. It supports four meta-actions:

ActionDescriptionKey fields
run_playbookExecute another playbook inlineplaybook, inputs
parallelRun step branches concurrentlybranches
conditionalExecute steps if condition is truecondition, then
loopRepeat steps until condition or max iterationsuntil, max_iterations, steps

Conditions use the syntax captures.key == value, captures.key != value, or captures.key (truthy check).

Example: Conditional + parallel

steps:
  - id: check-provider
    action: conditional
    executor: composite
    condition: "captures.provider == cloudflare"
    then:
      - id: setup-dns
        action: run_playbook
        playbook: cloudflare.dns.add-a-record
        inputs:
          zone: "{{zone}}"
          record_name: "{{subdomain}}"
          ip_address: "{{ip}}"
  - id: deploy-both
    action: parallel
    executor: composite
    branches:
      - steps:
          - id: provision-storage
            action: persist_provision
            profile: production
      - steps:
          - id: apply-infra
            action: tf_apply
            target_id: "{{target}}"
            resource_types: ["aws_s3_bucket"]

See also