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 and generates a tailored rig.json. It detects Docker Compose postgres and redis services, a Django backend (manage.py), a generic Python ASGI backend such as FastAPI (pyproject.toml or requirements.txt), and a Node dev server (package.json, run with npm, pnpm, yarn, or bun as its lockfile indicates):

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         ID        MODE     STATUS   SERVICES                          ROOT
pinpoint-leads  e9297fec  native   running  postgres:running, web:running     ~/code/pinpoint-leads
winnow-post     74376561  default  stopped  api:stopped                       ~/code/winnow-post
tertia-club     d7bfeefc  native   running  worker:running, ui:running        ~/code/tertia-club

Add -w, --wide to show the full instance identifier (<project>-<hash>) in an INSTANCE column.

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

rig ps --health

Targeted Teardown & Garbage Collection

Without a target, rig down stops the services of the current checkout. With a target, rig down stops a recorded instance from anywhere on your machine, even outside its checkout directory. The target must match either the project name or the full instance directory name (<project>-<hash>, as shown by rig ps --wide). Matching is case-insensitive. When a project name matches more than one instance, rig refuses with E_AMBIGUOUS and asks for the full instance identifier.

# Stop by project name
rig down pinpoint-leads

# Stop by full instance identifier
rig down pinpoint-leads-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",
      "compose_port": 5432
    }
  },
  "modes": {
    "native": {
      "services": {
        "backend": {
          "type": "fd",
          "cwd": "backend",
          "command": ".venv/bin/python -m app.main --fd {fd}",
          "healthcheck_path": "/healthz",
          "depends_on": ["db"]
        },
        "frontend": {
          "type": "port",
          "cwd": "frontend",
          "command": "npm run dev -- --port {port}",
          "healthcheck_path": "/",
          "depends_on": ["backend"],
          "env": {
            "VITE_API_PORT": "{backend_port}"
          }
        }
      }
    },
    "container": {
      "services": {
        "backend": {
          "type": "compose",
          "compose_file": "docker-compose.yml",
          "compose_service": "backend",
          "compose_port": 8000,
          "healthcheck_path": "/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.

Symmetrical Makefile Integration

Include examples/rig.mk in your root Makefile (include rig.mk), or inline its targets:

# Standard local dev targets for rig.
# Include this file in your project's Makefile: `include rig.mk` (or inline it).

.PHONY: up down local-up local-down backend-up backend-down ui-up ui-down status logs

RIG ?= rig
# Service for `make logs`, e.g. `make logs SERVICE=backend`.
SERVICE ?=

up:
	@$(RIG) up --scope full

down:
	@$(RIG) down --scope full

local-up:
	@$(RIG) up --scope local

local-down:
	@$(RIG) down --scope local

backend-up:
	@$(RIG) up --scope backend

backend-down:
	@$(RIG) down --scope backend

ui-up:
	@$(RIG) up --scope ui

ui-down:
	@$(RIG) down --scope ui

status:
	@$(RIG) status

logs:
	@$(RIG) logs $(SERVICE)

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