Local CI with agent-ci
This page shows how to run the GitHub Actions workflows on your own machine with agent-ci before you push, so you find a failing check quickly and fix it in the same loop.

You can run the repository's GitHub Actions workflows on your own machine before you push. CI means the checks that GitHub runs on every pull request. Running them locally finds a failure quickly, without a wait for GitHub. The loop is short: edit, run, see the failure, fix it, retry the failed step, push. The root AGENTS.md asks coding agents to check their changes this way before they report work as done.

The tool is agent-ci by RedwoodJS. It uses the official GitHub Actions runner binary, unchanged. So what passes on your machine passes on GitHub. It replaces the cloud cache with folders mounted from your machine. So node_modules, the pnpm store and the llama.cpp build results stay between runs at almost no cost.

What the repository provides


    .github/agent-ci.Dockerfile extends the official runner image. It creates /home/runner/.cache in advance, owned by the user runner. Without this, golangci-lint-action fails with permission denied, because Docker creates that directory as root when it mounts /home/runner/.cache/ms-playwright on top of it.

    The Local CI section of the root AGENTS.md holds the same instructions for coding agents.

.env.agent-ci is ignored by git. It is optional. You need it only to pass secrets into local runs, and most workflows do not need it.

One-time setup

    Docker Desktop. Install and start it. Verify with docker info.

    Tell agent-ci where Docker's socket is. Docker Desktop on macOS does not provide /var/run/docker.sock by default. agent-ci reads the standard DOCKER_HOST environment variable. Add this to ~/.zshrc (or ~/.bashrc):

    export DOCKER_HOST="unix://$HOME/.docker/run/docker.sock"

    Then source ~/.zshrc or open a new terminal. Verify with echo $DOCKER_HOST.

    Another way: in Docker Desktop → Settings → Advanced, turn on "Allow the default Docker socket to be used". That creates the /var/run/docker.sock link, and then you do not need the export.

    Pull the runner image (about 1.5 GB):

    docker pull ghcr.io/actions/actions-runner:latest

    Optional, macOS jobs. To run the macOS desktop-build workflows locally (Apple Silicon only):

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

    Without these, agent-ci skips macOS jobs and prints no warning. agent-ci does not support Windows jobs and always skips them.

Commands by area

Pick the command for the area you changed. -p is --pause-on-failure: it keeps the container running after a failure, so you can fix the problem and retry the same step. --github-token with no value gets the token from the gh CLI.

Changed area

Command

Frontend (web/desktop/shared/ui/editor)

npx @redwoodjs/agent-ci run -w .github/workflows/test-frontend-parallel.yml -p --github-token

Backend Go lint

npx @redwoodjs/agent-ci run -w .github/workflows/lint-go.yml -p

Backend Go tests

npx @redwoodjs/agent-ci run -w .github/workflows/test-go.yml -p

apps/**, the app environment

npx @redwoodjs/agent-ci run -w .github/workflows/test-agents.yml -p

hypermedia/**, these docs

npx @redwoodjs/agent-ci run -w .github/workflows/check-hypermedia.yml -p

vault/**

npx @redwoodjs/agent-ci run -w .github/workflows/dev-vault-image.yml -p --github-token

ops/** deploy script

npx @redwoodjs/agent-ci run -w .github/workflows/check-deploy-script.yml -p --github-token

Dependency change

npx @redwoodjs/agent-ci run -w .github/workflows/security-audit.yml -p

The fix-and-retry loop

When a step fails with -p, agent-ci pauses and prints a runner name such as agent-ci-3. The container keeps running, with all its caches.

# Edit the broken file in your editor npx @redwoodjs/agent-ci retry --name agent-ci-3

retry runs only the failed step again, in the same container. To run the whole job again from step 1, add --from-start. To stop, run npx @redwoodjs/agent-ci abort --name agent-ci-3.

What not to run locally

For everyday work, do not use --all and do not run dev-docker-images.yml. They include heavy llama.cpp Vulkan builds and the building of Docker images. These take more than 15 minutes and tell you nothing that test-go.yml does not.

You cannot check these workflows locally at all:

    Windows desktop builds. agent-ci does not support Windows runners.

    macOS code signing and notarization. Those steps need Apple secrets, which are kept off your disk on purpose. The build passes and the signing step fails. Run with --no-matrix if you want to test the build itself.

    Anything reading deploy secrets (S3, Sentry, Docker Hub). Those steps fail locally, as expected.

Troubleshooting

Docker does not appear to be running: your shell is not exporting DOCKER_HOST. See setup step 2 above. Verify with echo $DOCKER_HOST.

No such image: ghcr.io/actions/actions-runner:latest: the runner image is not pulled, or docker system prune removed it. Do setup step 3 again.

permission denied writing under /home/runner/.cache/...: .github/agent-ci.Dockerfile handles this. If a new tool needs another directory under .cache, add it to the install -d ... line in that Dockerfile.

The llama.cpp build hangs or fails on Vulkan: do not run dev-docker-images.yml locally. Use test-go.yml. It builds llama for the CPU only, which works on every machine, and the build is cached after the first run.

Step actions/setup-go@v5 is slow on first run: it downloads Go when the cache is cold. Later runs reuse it.

How it works

agent-ci runs the official GitHub Actions runner binary inside a Docker container. On your machine it imitates the parts of GitHub that the runner talks to: the Twirp endpoints, the Azure Block Blob protocol for artifacts, and the cache REST API. So the runner behaves as if it talks to GitHub.com. agent-ci mounts the caches and node_modules from your machine into /home/runner/... paths. So an install that takes minutes in remote CI takes seconds on a second local run. It is the real runner and not a copy of it, so a local run and a remote run behave almost exactly the same.

See also

    Contributing, for the checks each area expects and how to run them without agent-ci.

    Releasing, for the workflows a release tag starts.

    Working on Seed, the list of contributor guides.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime