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.

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.

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.

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.

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.

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

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

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

Run GitHub Actions workflow jobs locally.

Retry a paused runner after fixing the failure.

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

Abort a paused runner and tear down its container.

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

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.

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 environment variables always take precedence over .env.agent-ci entries.

By default, jobs run inside ghcr.io/actions/actions-runner:latest — the official self-hosted runner image. It includes the runner agent, Node.js, git, curl, jq, and unzip, but not build toolchains, python3, xz, or other tools that GitHub's hosted ubuntu-latest VM ships.

If a workflow fails with a missing tool, create a Dockerfile to add it:

# .github/agent-ci.Dockerfile
FROM ghcr.io/actions/actions-runner:latest
RUN sudo apt-get update \
 && sudo apt-get install -y --no-install-recommends <your-packages> \
 && sudo rm -rf /var/lib/apt/lists/*

Agent CI picks it up automatically — no flags, no config. The image is built once and cached by content hash.

For the full guide — directory form with COPY support, per-job overrides, common recipes (Rust, Node native modules, Go, Ruby, Nix), the AGENT_CI_RUNNER_IMAGE escape hatch, and build caching details — see runner-image.md.

Jobs with runs-on: macos-* run in a real, throwaway macOS VM on Apple Silicon hosts with tart and sshpass installed. On any other host (Linux, Intel Mac, or missing tools), macOS jobs are skipped with a clear reason message.

The VM uses the official cirruslabs images and is destroyed after the job finishes. The runner binary is fetched once and cached on the host.

Default image mapping:

• Only Apple Silicon hosts are supported — Virtualization.framework cannot run macOS guests on Intel Macs.
• Windows jobs (runs-on: windows-*) are not yet supported and always skip.

Agent CI connects to Docker via the AGENT_CI_DOCKER_HOST environment variable. By default it uses the local socket (unix:///var/run/docker.sock), but you can point it at any remote Docker daemon:

AGENT_CI_DOCKER_HOST=ssh://user@remote-server npx @redwoodjs/agent-ci run --workflow .github/workflows/ci.yml

Note: the standard DOCKER_HOST env var is not honoured. If you have it set for the regular Docker CLI, agent-ci exits with an error asking you to rename to AGENT_CI_DOCKER_HOST. This lets agent-ci target a different daemon than your shell's docker CLI without the two colliding — and it lets the value live in .env.agent-ci.

By default, Agent CI uses host.docker.internal for container-to-host DTU traffic and adds a default Docker host mapping:

• host.docker.internal:host-gateway

This keeps behavior OS-agnostic and works on Docker Desktop and modern native Docker.

If your setup is custom, use environment overrides:

• AGENT_CI_DTU_HOST — override the hostname/IP used by runner containers to reach DTU
• AGENT_CI_DOCKER_EXTRA_HOSTS — comma-separated host:ip entries passed to Docker ExtraHosts (full replacement for defaults)
• AGENT_CI_DOCKER_HOST_GATEWAY — override the default host-gateway token/IP for automatic mapping
• AGENT_CI_DOCKER_DISABLE_DEFAULT_EXTRA_HOSTS=1 — disable the default host.docker.internal mapping
• AGENT_CI_DOCKER_BRIDGE_GATEWAY — fallback gateway IP used when Agent CI runs inside Docker and cannot detect its container IP, and as an explicit DTU host override outside Docker when AGENT_CI_DTU_HOST is not set

When using a remote daemon (AGENT_CI_DOCKER_HOST=ssh://...), host-gateway resolves relative to the remote Docker host. If DTU is not reachable from that host, set AGENT_CI_DTU_HOST and AGENT_CI_DOCKER_EXTRA_HOSTS explicitly for your network.

When running multiple workflows (--all), Agent CI limits how many containers run at the same time to avoid running out of memory.

The limit is auto-detected using two factors:

• CPU: floor(cpuCount / 2)
• Memory: floor(availableDockerMemory / 4GB)

Whichever is lower wins. For example, on a machine with 14 CPUs and a Docker VM with 12 GB of RAM, the CPU limit is 7 and the memory limit is 2 — so 2 containers run at a time.

To check available memory, Agent CI reads MemAvailable from /proc/meminfo inside the Docker VM. This accounts for the VM's kernel, daemon, and any other running containers. If that fails, it falls back to docker info total memory minus 4 GB.

You can override the auto-detected limit with --jobs:

# Run at most 4 containers at a time
npx @redwoodjs/agent-ci run --all --jobs 4

# Run one at a time (safest, slowest)
npx @redwoodjs/agent-ci run --all --jobs 1

See compatibility.md for detailed GitHub Actions workflow syntax support.

Set the DEBUG environment variable to enable verbose debug logging. It accepts a comma-separated list of glob patterns matching the namespaces you want to see:

• Output goes to stderr so stdout stays clean for piping.
• If DEBUG is unset or empty, all debug loggers become no-ops (zero overhead).
• Pattern matching uses minimatch globs, so agent-ci:* matches all four namespaces.

DEBUG=agent-ci:* npx @redwoodjs/agent-ci run --workflow .github/workflows/ci.yml

The loop: commit → Agent CI runs → failure → your agent fixes the file in place with --pause-on-failure → retry the failed step → commit the fix → push. The bind-mounted cache and paused container are what make this loop tight enough to actually work — your agent isn't waiting minutes for a fresh install between attempts.

Install the agent skill:

npx skills add redwoodjs/agent-ci --skill agent-ci

This works with Claude Code, Cursor, Codex, and 40+ other agents. Then add to your agent instructions (CLAUDE.md, .cursorrules, AGENTS.md, etc.):

## CI

Install the agent-ci skill (one-time setup):

\`\`\`bash
npx skills add redwoodjs/agent-ci --skill agent-ci
\`\`\`

Before completing any work, run the `agent-ci` skill to validate your changes locally. If it fails, fix the issue and re-run. Do not report work as done until it passes.