Reactorcide is a small CI/CD system for ephemeral container or vm jobs. You can run the same job on a workstation, a VM worker, or a Kubernetes worker.
Reactorcide supports trusted CI definitions for source from outside contributors. It also supports named workflows, job dependencies, secret grants, authenticated workers, and GitHub webhooks. It is not attached to git, but git is the current implemented VCS, others may follow if needed.
- Run one local job: Installation and Deployment
- Install on a VM: VM Installation
- Install on Kubernetes: Kubernetes Deployment
- Connect GitHub: VCS Setup
- Write repository jobs: Job Definition Reference
- Understand the security boundary: Security Model
- Permit reviewed pull-request CI changes: Organizations and Trusted CI Policy
Use the Go version in coordinator_api/go.mod:
cd coordinator_api
go build -o reactorcide .
cd ..You need Docker, or containerd with nerdctl. The default backend is Docker.
Add --backend containerd when you use nerdctl.
./coordinator_api/reactorcide run-local \
./examples/jobs/hello-world.yamlrun-local mounts the current repository at /job/src and /job/ci. The CI
mount is read-only. Use --source-dir or --ci-dir when the tested source and
trusted CI definitions are in different repositories. The command uses the
host user by default. Use --as-runner to use the deployed runner user.
You can also give run-local one workflow file. Reactorcide evaluates the
selected workflow for --event and runs its jobs when the event matches.
Reactorcide writes the final result to
reactorcide-workflow-summary.json in the local workspace.
The summary contains variable names. It does not contain variable values.
./coordinator_api/reactorcide run-local \
--event pull_request_updated \
--max-parallel 4 \
./.reactorcide/workflows/pr.yamlThe CLI covers every coordinator operation. Set REACTORCIDE_API_URL and
REACTORCIDE_API_TOKEN, then use commands such as:
./coordinator_api/reactorcide jobs list --status failed
./coordinator_api/reactorcide workflows retry <workflow-id>
./coordinator_api/reactorcide projects create --file my-repo.yamlSee the CLI Reference.
You need Python 3.13 or later, uv, Go, and a container runtime.
./tools setup
./tools dev
./tools testThe development stack uses local development credentials. Do not use it for production.
coordinator_api/: CLI, REST API, workflow state, VCS integration, secrets, and worker protocolrunnerlib/: Job-side Python librarywebapp/: Optional management web applicationhelm_chart/: Kubernetes deploymentdeployment/: VM Compose deployment assetsjobs/: Build, test, and deployment jobs for Reactorcideexamples/: Job, pipeline, plugin, and API examples
The coordinator owns control-plane state. It connects to PostgreSQL, Corndogs, and object storage. Authenticated workers request work from the coordinator. Workers can use Docker, containerd, Kubernetes Jobs, or supported VM backends.
See System Design.
Run the database migrations, then create the first token:
./coordinator_api/reactorcide token create --name adminThe coordinator creates the default organization from
REACTORCIDE_DEFAULT_ORG. The first token is a global instance token. This
bootstrap does not require a user row. Create narrower service or user tokens
after you configure organizations and roles.
Keep the first token in a secret store. Do not put it in a job definition. The coordinator gives remote jobs a short-lived job token. It does not give them the instance token.
GitHub webhook events are operational. A GitLab client exists, but its webhook event normalization is incomplete. GitLab events do not start jobs. Complete the common event mapping before you use GitLab for CI triggers.
Use the Documentation Index for all operator, job author, and contributor guides.
Reactorcide is in active development. Review image tags, deployment defaults, and security settings before production use.
Join the Catalyst Community Discord for project discussion.