rig

Zero-dependency, zero-daemon developer environment supervisor and process runner for multi-service repositories.

PyPI Package • Quick Start • Comparison • Socket Inheritance • Machine Supervision • AI Agent Protocol • CLI Reference

The Acute Friction

Local multi-service development across multiple git branches and checkouts is routinely broken by five recurring headaches:

Feature Comparison

How rig compares against standard development orchestrators:

The 3-Step Fast Track

1. Install Globally (User Space)

Install rig-cli from PyPI using standard, isolated tool runners:

# Recommended (pipx)
pipx install rig-cli

# Ultra-fast alternative (uv)
uv tool install rig-cli

2. Initialize Any Repository

Run rig init inside your project root. rig inspects your directory, detects Docker Compose, FastAPI, Flask, Django, Vite, or Next.js, and generates a tailored rig.json:

rig init

Preview detected services without writing to disk:

rig init --dry-run

3. Launch and Supervise

# Start all services in the active mode
rig up

# Check status of the local checkout
rig status

# Inspect service logs
rig logs backend -n 50

# Stop services in this checkout
rig down

Machine-Wide Supervision (rig ps)

rig maintains a machine-wide state registry under $XDG_STATE_HOME/rig/instances/ (~/.local/state/rig/instances/). Every project instance records its directory, PID, PGID, active mode, and allocated ports.

rig ps

PROJECT         INSTANCE      MODE       STATUS    ACTIVE  PORTS                    ROOT
pinpoint-leads  e9297fec      native     running   3/3     postgres:5432, web:3004  /Users/dev/code/pinpoint-leads
winnow-post     74376561      default    stopped   0/1     -                        /Users/dev/code/winnow-post
tertia-club     d7bfeefc      native     running   2/2     worker:8004, ui:3003     /Users/dev/code/tertia-club

Add --health to probe HTTP endpoints for real-time health checks:

rig ps --health

Targeted Teardown & Garbage Collection

Stop projects from anywhere on your machine, even outside their checkout directory:

# Stop by project name slug
rig down pinpoint-leads

# Stop by specific instance ID
rig down e9297fec

# Stop ALL running instances across the entire machine
rig down --all

# Clean up stale instance state files
rig prune

# Force-kill lingering orphaned processes and prune
rig prune --force

Zero-Race Socket Inheritance (type: "fd")

When a service specifies type: "fd", rig eliminates the classic time-of-check to time-of-use (TOCTOU) port race:

┌─────────┐      1. socket(AF_INET, SOCK_STREAM)
│   rig   │ ──── 2. bind("127.0.0.1", 0)  ───► OS Kernel assigns port
│         │ ──── 3. listen(128)
└────┬────┘
     │           4. subprocess.Popen(..., pass_fds=[fd])
     ▼
┌─────────┐
│ Uvicorn │ ──── 5. uvicorn.run(..., fd=sock.fileno())
└─────────┘      (Socket is NEVER closed between allocation and server startup)

Python / Uvicorn Example

import argparse
import socket
import uvicorn

parser = argparse.ArgumentParser()
parser.add_argument("--fd", type=int, default=None)
args, _ = parser.parse_known_args()

if args.fd is not None:
    sock = socket.fromfd(args.fd, socket.AF_INET, socket.SOCK_STREAM)
    uvicorn.run("main:app", fd=sock.fileno())
else:
    uvicorn.run("main:app", host="127.0.0.1", port=8000)

Multi-Stack Modes (native vs container)

Define base infrastructure and mode overlays in a single rig.json:

{
  "$schema": "https://raw.githubusercontent.com/evgesha9400/rig/main/rig.schema.json",
  "project": "my-app",
  "default_mode": "native",
  "services": {
    "db": {
      "type": "compose",
      "compose_file": "docker-compose.yml",
      "compose_service": "postgres",
      "health_tcp": 5432
    }
  },
  "modes": {
    "native": {
      "services": {
        "backend": {
          "type": "fd",
          "cwd": "backend",
          "command": ".venv/bin/python -m app.main --fd {fd}",
          "health": "/healthz",
          "depends_on": ["db"]
        },
        "frontend": {
          "type": "port",
          "cwd": "frontend",
          "command": "npm run dev -- --port {port}",
          "health": "/",
          "depends_on": ["backend"],
          "env": {
            "VITE_API_PORT": "{backend_port}"
          }
        }
      }
    },
    "container": {
      "services": {
        "backend": {
          "type": "compose",
          "compose_file": "docker-compose.yml",
          "compose_service": "backend",
          "health": "http://127.0.0.1:8000/healthz",
          "depends_on": ["db"]
        }
      }
    }
  }
}

Collision-Safe Mode Switching

rig prevents conflicting processes from running simultaneously:

# Blocked with exit code 3 (E_MODE_CONFLICT) to prevent colliding ports/services:
rig up --mode container

# Cleanly tears down native services first and launches container mode:
rig up --mode container --switch

AI Agent & Automation Protocol

rig is built for autonomous execution by AI agents (Claude Code, AntiGravity, Codex, Cursor) and CI/CD pipelines:

Why AI Coding Assistants Use rig

1. Deterministic Process Control: AI agents frequently lose control of background tasks or suffer port collisions when re-running test servers. rig manages the full process lifecycle with PID/PGID process groups.
2. Predictable JSON Responses: Agents never have to scrape ANSI text or parse unpredictable terminal formatting.
3. Actionable Resolution Hints: When an error occurs, rig returns an exact diagnostic hint for automated recovery.

Universal --json Output Envelope

Every CLI command supports --json and emits a typed, deterministic envelope:

{
  "schema": "rig.status/1",
  "ok": true,
  "data": {
    "project": "pinpoint-leads",
    "instance": "pinpoint-leads-e9297fec",
    "mode": "native",
    "generation": 1,
    "services": {
      "backend": {
        "running": true,
        "type": "fd",
        "port": 8003,
        "url": "http://127.0.0.1:8003",
        "pid": 59608
      }
    }
  }
}

Errors provide actionable resolution hints:

{
  "schema": "rig.error/1",
  "ok": false,
  "error": {
    "code": "E_MODE_CONFLICT",
    "message": "Instance is running in mode 'native'; cannot start mode 'container'",
    "hint": "Pass --switch to stop the active mode first, or run 'rig down' before starting a new mode."
  }
}

Deterministic Exit Codes

CLI Command Reference

Configuration Reference (rig.json)

To inspect or validate the JSON Schema directly:

rig schema

Zero Runtime Dependencies

rig is committed to zero third-party runtime dependencies. It relies exclusively on the Python standard library (socket, subprocess, os, signal, json, fcntl, shlex, dataclasses, pathlib).

• No background daemons (systemd, dockerd, supervisord) required to orchestrate native processes.
• No Node.js or Ruby runtimes required.
• Instantaneous startup with file-backed atomic state.

Direct Drop-in Usage

Because rig has zero external dependencies, you can also drop the orchestrator entry point directly into any repository without installing it:

curl -fsSL https://raw.githubusercontent.com/evgesha9400/rig/main/src/rig/cli.py -o scripts/rig.py
python3 scripts/rig.py up

Symmetrical Makefile Integration

Drop these targets into your root Makefile for zero-friction developer ergonomics:

RIG ?= rig

up:
	@$(RIG) up

down:
	@$(RIG) down

status:
	@$(RIG) status

ps:
	@$(RIG) ps

check:
	@$(RIG) check

logs:
	@$(RIG) logs -n 100

Links & Ecosystem

• PyPI Package: https://pypi.org/project/rig-cli/
• GitHub Repository: https://github.com/evgesha9400/rig
• JSON Schema: https://raw.githubusercontent.com/evgesha9400/rig/main/rig.schema.json
• Issue Tracker: https://github.com/evgesha9400/rig/issues
• Releases & Changelog: https://github.com/evgesha9400/rig/releases

License

MIT © 2026 Evgeny Aleshin