redwoodjs__local-ci/packages/cli

Agent CI

Agent CI is local CI for agents. It pauses when a workflow fails, allowing your agent to fix the issue and resume the workflow. Think of it as "live-reload for CI."

Agent CI runs your GitHub Actions workflows locally using the same official GitHub Action runners — the exact same binaries that power GitHub-hosted CI. What Agent CI emulates is the GitHub.com API itself, so actions like actions/checkout, actions/setup-node, and actions/cache work out of the box without hitting GitHub's servers.

Why Agent CI?

Traditional CI is a fire-and-forget loop: push, wait, fail, read logs, push again. Every retry pays the full cost of a new run.

Agent CI runs on any machine that can run a container. When a step fails the run pauses — the container stays alive with all state intact. Your edits are synced into the container on retry, so you can fix the issue and retry just the failed step — no checkout, no reinstall, no waiting. This makes it ideal for AI agents: point an agent at the failure, let it fix and retry in a tight loop — without the cost of a full remote CI cycle each time.

Prerequisites

• Docker — A running Docker provider:
  • macOS: OrbStack (recommended) or Docker Desktop
  • Linux: Native Docker Engine or Docker Desktop

Installation

npm install -D @redwoodjs/agent-ci

Usage

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

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

Remote Docker

Agent CI connects to Docker via the 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:

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

Docker host resolution for job containers

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

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
--pause-on-failure	-p	Pause on step failure for interactive debugging
--quiet	-q	Suppress animated rendering (also enabled by AI_AGENT=1)
--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)

YAML Compatibility

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

Debugging

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:

Value	What it shows
DEBUG=agent-ci:*	All debug output
DEBUG=agent-ci:cli	CLI-level logs only
DEBUG=agent-ci:runner	Runner/container logs only
DEBUG=agent-ci:dtu	DTU mock-server logs only
DEBUG=agent-ci:boot	Boot/startup timing logs only
DEBUG=agent-ci:cli,agent-ci:dtu	Multiple namespaces

• 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 agent-ci run