开源AI工作流Railyard

Prerequisites

• Go 1.26+
• MySQL 8.0+ — SQL database
• tmux — terminal multiplexer
• AI coding CLI (at least one):
• Claude Code (default) — npm install -g @anthropic-ai/claude-code
• Codex — npm install -g @openai/codex
• Gemini — npm install -g @google/gemini-cli
• Copilot — gh extension install github/gh-copilot
• Docker (optional) — for pgvector/CocoIndex semantic search
• GitHub CLI (optional, required when require_pr: true) — install
• Python 3.13+ (optional) — for CocoIndex semantic search

Dependencies

ry car dep add <car-id> --blocked-by <blocker-id> ry car dep list <car-id> ry car dep remove <car-id> --blocked-by <blocker-id> ```

Optional: CocoIndex semantic search (requires Docker + Python 3.13+)

Manual Setup

If you prefer to set things up step by step:

1. Build the CLI

go build -o ry ./cmd/ry/

2. Start MySQL

```bash

Start MySQL server (install via your package manager if not already installed)

Setup

ry init                                 # Interactive setup: detect languages, generate config, start MySQL
ry init -c railyard.yaml --yes          # Non-interactive with all defaults
ry init --skip-db --skip-cocoindex      # Skip MySQL and CocoIndex setup
ry init -u myuser -p 3307              # Custom port/user
ry init --password secret               # Set MySQL password
ry migrate -c railyard.yaml             # Migrate existing repo to .railyard/ directory structure

Kubernetes Deployment

Railyard can run on Kubernetes using the provided Helm chart. Instead of tmux sessions, engines run as Kubernetes pods with auto-scaling, TLS-secured database connections, and multi-project isolation.

helm install railyard charts/railyard \
  --set git.owner=yourname \
  --set git.repo=git@github.com:org/repo.git \
  --set auth.apiKey=$ANTHROPIC_API_KEY

For multi-project setups, set the project field in your railyard.yaml to isolate namespaces, database names, and branch prefixes per project.

For detailed configuration and setup guides, see:

• charts/railyard/README.md — full Helm chart configuration reference
• docs/k8s-authentication.md — authentication setup (API keys, OAuth, Bedrock, Vertex, Foundry)
• docs/k8s-deployment.md — step-by-step deployment guide
• docs/k8s-local-testing.md — local testing with minikube

Setup

```bash

Initialize pgvector (Docker), Python venv, and schema

ry cocoindex init -c railyard.yaml

The quickstart.sh script does this automatically if Docker is available

```

This starts a PostgreSQL 16 container with pgvector on port 5481 (auto-detects conflicts), creates a Python 3.13+ venv at cocoindex/.venv, installs dependencies, and runs migrations.

Build overlay for a specific engine

ry overlay build --engine eng-abc123 -c railyard.yaml

build_timeout_sec: 60

tracks: - name: backend language: go file_patterns: ["cmd/", "internal/", "pkg/**", "*.go"] engine_slots: 3 # Max concurrent engines on this track test_command: "go test ./..." # Command to validate before merge (default: go test ./...) conventions: go_version: "1.26" style: "stdlib-first, no frameworks" test_framework: "stdlib table-driven"

- name: frontend language: typescript file_patterns: ["src/**", ".ts", ".tsx", "*.css"] engine_slots: 3 agent_provider: codex # Per-track override (inherits global if omitted) test_command: "npm test" # Any shell command works conventions: framework: "Next.js 15" styling: "Tailwind CSS" ```

Quickstart

The quickstart script handles everything: installing prerequisites, building the ry binary, starting MySQL, initializing the database, and optionally setting up pgvector for semantic code search.

git clone https://github.com/zulandar/railyard.git
cd railyard
chmod +x quickstart.sh
./quickstart.sh

Already have a railyard.yaml in your repo? If you're cloning an existing Railyard project to a new machine, see New Machine Setup — you don't need ry init.

Usage

Tutorials

• Build a Todo App with Railyard — Step-by-step walkthrough building an API with multiple agents working in parallel

Playwright PR Demo (Frontend UI Evidence)

An opt-in, per-track feature: when enabled, the engine prompt instructs the agent to commit a Playwright spec demonstrating the user-visible behavior of its change, and Yardmaster's draft PR body gains a pointer to the spec file. The project's own CI is expected to run the spec (with video recording on) and surface the recording — Railyard does not run Playwright itself.

Enable per track in railyard.yaml:

tracks:
  - name: frontend
    language: typescript
    playwright:
      enabled: true
      spec_path: "tests/pr-demos"
      template: "tests/pr-demos/_template.spec.ts"  # optional

See Playwright PR Demo Setup Guide for the full schema, helm/k8s equivalents, CI responsibilities, and known limitations.

Configuration

Add the CocoIndex section to your railyard.yaml:

cocoindex:
  database_url: "postgresql://cocoindex:cocoindex@localhost:5481/cocoindex"
  overlay:
    enabled: true           # Auto-build overlay indexes for engines
    auto_refresh: true      # Rebuild overlay when engine switches cars
    build_timeout_sec: 60   # Timeout for overlay builds

When database_url is set, overlay indexing is enabled by default. Engines automatically get MCP-powered semantic search.

Configuration Reference

See railyard.example.yaml for a copy-paste ready template.

```yaml owner: alice # Your identity (branch prefix: ry/alice/...) repo: git@github.com:org/repo.git # Target repository agent_provider: claude # AI CLI provider (claude, codex, gemini, copilot)

Plugins

Railyard exposes a compile-time plugin SDK for private integrations (for example, enterprise observability connectors). The OSS ry binary continues to build and run identically with zero plugins registered — a separate private repo can import railyard as a Go module and produce a custom binary that side-effect imports the plugins it wants.

• Plugin authoring guide — lifecycle, host API, configuration conventions, testing patterns, and the production checklist
• Hello-world example — minimal working plugin (subscribes to CarCreated, logs each event) verified on every CI run