~0 ms caching

Agent CI replaces GitHub's cloud cache with local bind-mounts. node_modules, the pnpm store, Playwright browsers, and the runner tool cache all live on your host filesystem and are mounted directly into the container — no upload, no download, no tar/untar. The first run warms the cache; every subsequent run starts with hot dependencies instantly.

Pause on failure

Step 6 failed. Fix the file. Retry just that step. Green. No checkout, no reinstall, no waiting.

When a step fails, Agent CI pauses instead of tearing down. The container stays alive with all state intact — environment variables, installed tools, intermediate build artifacts. Your edits on the host are synced into the container, so you (or your AI agent) can fix the issue and retry just the failed step.

Real GitHub Actions Runner, real compatibility

Agent CI does not re-implement GitHub Actions. It emulates the server-side API surface — the Twirp endpoints, the Azure Block Blob artifact protocol, the cache REST API — and feeds jobs to the unmodified, official runner. If your workflow runs on GitHub, it runs here.

Prerequisites

• Docker — a running Docker provider:

  • macOS: OrbStack (recommended) or Docker Desktop
  • Linux: Native Docker Engine or Docker Desktop

• Optional — for runs-on: macos-* jobs (Apple Silicon Macs only):

  • tart — brew install cirruslabs/cli/tart
  • sshpass — brew install hudochenkov/sshpass/sshpass

  Without both, macOS jobs are skipped with a reason. See macOS jobs below.

Quick start

# Run a specific workflow
npx @redwoodjs/agent-ci run --workflow .github/workflows/ci.yml

# Run all relevant workflows for the current branch
npx @redwoodjs/agent-ci run --all

Agent CI runs against your current working tree — uncommitted changes are included automatically. No need to commit or stash before running.

Committing is optional, but it's a useful pattern: commit → run → fail → fix with --pause-on-failure → retry → commit the fix. When you do commit, the commit becomes a save point you can return to if the fix makes things worse. Your AI agent benefits from the same pattern — it can roll back to a known-good state before trying a different fix.

Retry a failed step

npx @redwoodjs/agent-ci retry --name <runner-name>

CLI reference

agent-ci run

Run GitHub Actions workflow jobs locally.

| Flag | Short | Description | | -------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | --workflow <path> | -w | Path to the workflow file | | --all | -a | Discover and run all relevant workflows for the current branch | | --jobs <n> | -j | Max concurrent containers (overrides auto-detection) | | --pause-on-failure | -p | Pause on step failure for interactive debugging | | --quiet | -q | Suppress animated rendering (also enabled by AI_AGENT=1) | | --json | | Emit NDJSON event stream on stdout (also enabled by AGENT_CI_JSON=1); see Agent output mode | | --no-matrix | | Collapse all matrix combinations into a single job (uses first value of each key) | | --github-token [<token>] | | GitHub token for fetching remote reusable workflows (auto-resolves via gh auth token if no value given). Also available as AGENT_CI_GITHUB_TOKEN env var | | --commit-status | | Post a GitHub commit status after the run (requires --github-token) |

agent-ci retry

Retry a paused runner after fixing the failure.

| Flag | Short | Description | | ----------------- | ----- | --------------------------------------------- | | --name <name> | -n | Name of the paused runner to retry (required) | | --from-step <N> | | Re-run from step N, skipping earlier steps | | --from-start | | Re-run all steps from the beginning |

Without --from-step or --from-start, retry re-runs only the failed step (the default).

agent-ci abort

Abort a paused runner and tear down its container.

| Flag | Short | Description | | --------------- | ----- | --------------------------------------------- | | --name <name> | -n | Name of the paused runner to abort (required) |

Secrets

Workflow secrets (${{ secrets.FOO }}) are resolved in order:

1. .env.agent-ci file in the repo root (KEY=VALUE syntax, # comments supported)
2. Shell environment variables — any env var matching a required secret name acts as a fallback
3. --github-token — automatically provides secrets.GITHUB_TOKEN

# All three approaches work:
# 1. .env.agent-ci file
echo "CLOUDFLARE_API_TOKEN=xxx" >> .env.agent-ci

# 2. Inline env vars
CLOUDFLARE_API_TOKEN=xxx agent-ci run -w .github/workflows/deploy.yml

# 3. --github-token for GITHUB_TOKEN specifically
agent-ci run -w .github/workflows/ci.yml --github-token

Vars

Workflow variables (${{ vars.FOO }}) are provided exclusively via the --var CLI flag. There's no file-based lookup and no fallback to shell environment variables — this keeps workflow vars distinct from shell env vars and ensures every value is explicit on the command line.

agent-ci run -w .github/workflows/deploy.yml \
  --var DEPLOY_ENV=production \
  --var API_URL=https://api.example.com

If a workflow references a var (${{ vars.FOO }}) and no matching --var FOO=... flag is passed, the run fails with a message listing the missing vars.

Environment variables

All configuration is available via environment variables. For persistent machine-local overrides, create a .env.agent-ci file in your project root — Agent CI loads it automatically (KEY=VALUE syntax, # comments supported).

Only AGENT_CI_*-prefixed keys from .env.agent-ci are applied to the CLI process environment (so they influence Docker/network resolution, etc.). Non-prefixed keys in the file are still resolved as workflow secrets via ${{ secrets.FOO }}. Shell env