Agent CI

Run GitHub Actions on your machine. Caching in ~0 ms. Pause on failure. Fix and retry — before you commit, before you push.

Agent CI is a ground-up rewrite of the GitHub Actions orchestration layer that runs entirely on your own machine. It doesn't wrap or shim the runner: it replaces the cloud API that the official GitHub Actions Runner talks to, so the same runner binary that executes your jobs on GitHub.com executes them locally, bit-for-bit.

Actions like actions/checkout, actions/setup-node, and actions/cache work out of the box — no patches, no forks, no network calls to GitHub. Dependencies that took a couple of minutes to install on GitHub's runners install in a few seconds on the second run, because the cache is bind-mounted — not uploaded, downloaded, or unpacked.

Why Agent CI?

Remote CI is the final gatekeeper — it runs on every push and decides what ships. That's its job. The problem is what happens when it fails: you push, you wait, you read logs, you push again. Every retry pays the full cost of a fresh run, and the gatekeeper ends up being used as a debugger.

Agent CI is a pre-flight check that runs on your own machine before you commit. Catch the failure in seconds, fix it locally, only push work that's already green — and let remote CI stay the gatekeeper.

Existing "run actions locally" tools either re-implement steps in a compatibility layer or require you to maintain a separate config. Agent CI does neither.

~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.

For workflows with several independent jobs, use --prewarm-through <workflow:job:step-id> to warm node_modules once before the real jobs start in parallel. The selected step must have a stable id. Agent CI runs a disposable copy of that job from the beginning through the selected step, then runs the real workflows normally. This avoids parallel cold installs writing to the same shared node_modules mount without patching package-manager tools. You can also set AGENT_CI_PREWARM_THROUGH in .env.agent-ci to make this automatic for a repo; Agent CI warns when cold parallel install jobs look likely and no prewarm setting is present.

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.

Rust runner from source

The npm package keeps npx @redwoodjs/agent-ci on the TypeScript execution path. The Rust runner is available in this repository for parity testing, but published npm installs do not include a native runner yet. Native npm platform packages and release archives are deferred until the release workflow builds, stages, and verifies real target binaries.

To try the Rust runner from a checkout, build or run it directly with Cargo:

cargo run -p agent-ci -- run --workflow .github/workflows/ci.yml
# or
cargo build --release -p agent-ci
./target/release/agent-ci run --workflow .github/workflows/ci.yml

The development wrapper can also build and run the Rust binary from a checkout:

AGENT_CI_FORCE_RUST=1 pnpm agent-ci-dev run --workflow .github/workflows/ci.yml

For published npm installs, AGENT_CI_FORCE_RUST=1 npx @redwoodjs/agent-ci ... is expected to fail until native binary packaging lands. To force the TypeScript path explicitly, run with AGENT_CI_FORCE_TYPESCRIPT=1 or AGENT_CI_FORCE_TS=1.

Retry a failed step

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

CLI reference

agent-ci run

Run GitHub Actions workflow jobs locally.