Reactorcide

A minimalist CI/CD system for serious engineering teams. Works with open source or business needs, with particular focus on security for outside contributions.

Run jobs from your laptop just as easily as from the full system. If your VCS provider is down, fine - it's just building blocks.

Reactorcide runs isolated jobs locally, on single-VM workers, or as Kubernetes Jobs. Workflow-triggered jobs are grouped under a single workflow view, PR comment, and workflow-named VCS status.

Quick Start

1. Build the CLI

cd coordinator_api && go build -o reactorcide . && cd ..

# Optionally add to PATH
sudo cp coordinator_api/reactorcide /usr/local/bin/

2. Initialize Secrets Storage

# Initialize encrypted secrets vault
reactorcide secrets init

# Add secrets (e.g., for VM deployment)
reactorcide secrets set --stdin reactorcide/deploy ssh_private_key < ~/.ssh/id_ed25519

3. Deploy to a VM

Create an overlay file at ~/.config/reactorcide/my-vm.yaml:

environment:
  REACTORCIDE_DEPLOY_HOST: "your-vm-hostname"
  REACTORCIDE_DEPLOY_USER: "your-username"
  REACTORCIDE_DEPLOY_DOMAINS: "reactorcide.example.com"

Run the deployment:

REACTORCIDE_SECRETS_PASSWORD="<your-secrets-password>" \
  reactorcide run-local \
  --job-dir ./ \
  -i ~/.config/reactorcide/my-vm.yaml \
  ./jobs/deploy-to-vm.yaml

4. Create an API Token

After deployment, create a token to authenticate with the API:

# For VM deployment
ssh your-vm-hostname "cd ~/reactorcide && docker compose -f docker-compose.prod.yml exec coordinator-api /reactorcide token create --name my-token"

# For Kubernetes deployment
kubectl exec -n reactorcide deploy/reactorcideapp -- /reactorcide token create --name my-token

Save the returned token - it cannot be retrieved again.

The same reactorcide secrets subcommands can manage server-side secrets when REACTORCIDE_API_URL and REACTORCIDE_API_TOKEN are set, or when --api-url and --token are passed.

5. Use the API

# Check API health
curl http://your-vm-hostname:6080/api/v1/health

# List jobs (authenticated)
curl -H "Authorization: Bearer <your-token>" \
  http://your-vm-hostname:6080/api/v1/jobs

Local Development

# Start local dev stack
./tools dev

# Run tests
./tools test

# Build Docker images locally (for development)
./tools docker-build

Running Jobs Locally

REACTORCIDE_SECRETS_PASSWORD="<your-secrets-password>" \
  reactorcide run-local --job-dir ./ ./jobs/build-all.yaml

run-local bind-mounts --job-dir by default and runs as your host uid so generated files remain writable. Jobs can opt into root with run_as.user: root or worker parity with run_local.user: runner / --as-runner. Tooling prefers containerd/nerdctl when available and falls back to Docker.

Documentation

• DESIGN.md - Complete system architecture and design principles
• AGENTS.md - Implementation guidance for AI assistants and contributors
• docs/runtime-behavior.md - Local, VM, Kubernetes, path, and run identity behavior
• docs/workflow-design.md - Workflow DAGs, dependency handling, workflow vars, and PR status/comment behavior
• docs/vcs-credentials-and-secret-grants.md - Project/org VCS credentials, webhook secrets, and job secret grants
• runnerlib/DESIGN.md - Detailed runnerlib architecture and API
• docs/ - Additional documentation

Philosophy

• Isolation First: Run jobs from a known state in isolated containers
• Configuration Flexibility: System config and job config are separate
• VCS Agnostic: No hard ties to specific VCS providers
• Local Development: Run jobs from your laptop as easily as from the full system
• Building Blocks: Modular components that can be combined as needed
• Security by Design: Built with outside contributions and security in mind

Components

• reactorcide CLI - Main binary for running jobs, managing secrets, serving API
• runnerlib - Python library for job execution inside containers
• Coordinator API - REST API for job management and orchestration
• Worker - Distributed job processing with Corndogs task queue; supports Docker, containerd/nerdctl, and Kubernetes Jobs

Project Status

Active development. Join the Catalyst Community Discord to discuss and contribute.