README
¶
rig
The AI-integrated pilot for every service you run. Manage every part of your software from the terminal:
services, infrastructure, data, Kubernetes, logs, metrics, tests. Local processes, docker or Kubernetes;
Go, Python, Node, Java, Rust or anything that runs. Describe it once in rig.yaml, then run, watch and tune
it all from one CLI and one terminal UI.
- Plugin-based: every runtime, database, broker, metrics or logs backend is an adapter behind one registry. New components plug in without touching the core, and contributions are welcome.
- AI built in:
@on any screen chats about what it shows and can act on it; query prompts get AI autocomplete. Works with opencode (free models, no login needed), Claude Code, OpenAI or any OpenAI-compatible endpoint, Anthropic, DeepSeek and 9router.
 |
 |
 |
 |
 |
What it does
- Run: up in dependency order, start, stop, restart, scale, build, deploy, exec, debug
- Watch: merged logs you can query by field, Grafana-style dashboards, traces, alerts
- Data: browse and edit databases, Redis, RabbitMQ, Kafka, key-value config; saved queries on a schedule
- Kubernetes: manifests as a graph, edited field by field, synced from the cluster; HPAs, namespaces
- Test and load: test suites with live results, load generators with rate and instances
- AI:
@chat on every screen, inline query completions,@?plain-language queries;rig mcpgives agents every tool - Any stack: not just Go; Python, Node, Java, Rust, any image or binary;
rig initreads compose files, manifests and sources
Install
curl -fsSL https://raw.githubusercontent.com/goxang/rig/main/install.sh | sh
Linux and macOS (amd64, arm64). Windows: the .zip on the releases page.
With Go 1.23+: go install github.com/goxang/rig/cmd/rig@latest.
Start
rig init # rig.yaml from what the project has: compose, manifests, sources
rig doctor # what is missing: tools, cluster or daemon, variables, ports, components
rig up # everything, in dependency order
rig # the terminal UI; ? lists the keys of every screen
No rig.yaml yet? rig up && rig still work: rig infers the project in memory as rig init would,
and writes nothing until you run rig init.
On a project that already has a rig.yaml: rig env lists its environments, -e <name> picks one.
A small rig.yaml:
project: shop
default: docker
services:
api:
depends_on: [db]
build: { go: ./cmd/api }
ports: { http: 8080, metrics: 9090 }
health: { port: http, path: /healthz }
db: { role: infra, image: "postgres:17", ports: { pg: 5432 } }
environments:
docker: { runtime: { type: docker } }
kind: { runtime: { type: kind, cluster: shop, manifests: [deploy] } }
components:
db: { type: sql, driver: postgres, addr: "svc://db:5432", user: app, password: "${DB_PASSWORD}" }
Try one of the examples: cd examples/shop && rig up && rig.
Docs
- Guide: CLI, every screen and its keys, AI, GoLand, agents
- Config: every
rig.yamlkey - Design: how rig is built, writing an adapter
- Manifests: a manifest layout that works well with rig
All of it ships in the binary too: rig docs guide.
Contributing
rig is open to contributions: new adapters, screens, fixes, docs. Design shows how to
write an adapter. go vet ./... && go test -race ./... must pass. Commits follow Conventional Commits; every green push
to main is released (feat: minor, anything else patch).
License
Directories
¶
| Path | Synopsis |
|---|---|
|
adapters
|
|
|
all
Package all registers every adapter bundled with rig; a custom binary imports it plus its own.
|
Package all registers every adapter bundled with rig; a custom binary imports it plus its own. |
|
builder/command
Package command builds with the service's own build.command (ko, bazel, buildpacks, a Makefile, ...).
|
Package command builds with the service's own build.command (ko, bazel, buildpacks, a Makefile, ...). |
|
builder/docker
Package docker builds images with `docker build` and pushes them when the environment has a registry.
|
Package docker builds images with `docker build` and pushes them when the environment has a registry. |
|
builder/golang
Package golang builds a Go main package on this machine and puts the binary on a base image as one layer, with no Docker daemon and no in-container module download: the local build cache makes rebuilds take seconds.
|
Package golang builds a Go main package on this machine and puts the binary on a base image as one layer, with no Docker daemon and no in-container module download: the local build cache makes rebuilds take seconds. |
|
cache/redis
Package redis is the cache adapter for Redis and protocol-compatible servers (Valkey, KeyDB, Dragonfly).
|
Package redis is the cache adapter for Redis and protocol-compatible servers (Valkey, KeyDB, Dragonfly). |
|
database/sql
Package sql is the database adapter for SQL servers: one implementation, a dialect per driver (postgres, mssql, mysql) for listing, creating and dropping databases.
|
Package sql is the database adapter for SQL servers: one implementation, a dialect per driver (postgres, mssql, mysql) for listing, creating and dropping databases. |
|
debugger/delve
Package delve attaches a headless Delve server to a running Go service: to the local process directly, or inside the container (the image needs dlv and the pod SYS_PTRACE) with the port forwarded.
|
Package delve attaches a headless Delve server to a running Go service: to the local process directly, or inside the container (the image needs dlv and the pod SYS_PTRACE) with the port forwarded. |
|
hosts/ssh
Package ssh manages servers over the system ssh client, so ~/.ssh/config, agents, keys and jump hosts work exactly as they do in a terminal.
|
Package ssh manages servers over the system ssh client, so ~/.ssh/config, agents, keys and jump hosts work exactly as they do in a terminal. |
|
kv/consul
Package consul is the KV adapter for Consul's HTTP API.
|
Package consul is the KV adapter for Consul's HTTP API. |
|
loadgen
Package loadgen holds pieces shared by the load generator adapters (command, http, kv).
|
Package loadgen holds pieces shared by the load generator adapters (command, http, kv). |
|
loadgen/command
Package command wraps any load tool behind shell commands: start, stop, rate (with {rate}) and status, whose output may be JSON {"running":..,"rate":..,"sent":..,"failed":..}.
|
Package command wraps any load tool behind shell commands: start, stop, rate (with {rate}) and status, whose output may be JSON {"running":..,"rate":..,"sent":..,"failed":..}. |
|
loadgen/http
Package http is a built-in open-model load generator: requests go out at a fixed rate whatever the latency (no coordinated omission), from this process, for as long as rig runs.
|
Package http is a built-in open-model load generator: requests go out at a fixed rate whatever the latency (no coordinated omission), from this process, for as long as rig runs. |
|
loadgen/kv
Package kv drives load generators that run as services and read their rate from a key-value store: the rate is written to a key (or one JSON field of it), start and stop scale the generator services, and counters come from metrics queries when configured.
|
Package kv drives load generators that run as services and read their rate from a key-value store: the rate is written to a key (or one JSON field of it), start and stop scale the generator services, and counters come from metrics queries when configured. |
|
logs/loki
Package loki reads logs from Grafana Loki: following polls query_range, ad hoc queries take LogQL.
|
Package loki reads logs from Grafana Loki: following polls query_range, ad hoc queries take LogQL. |
|
logs/runtime
Package runtime serves logs straight from the runtime (kubectl logs, docker logs, local log files), merged across services.
|
Package runtime serves logs straight from the runtime (kubectl logs, docker logs, local log files), merged across services. |
|
messaging/kafka
Package kafka reads and manages Kafka through its own protocol: topics with their sizes and the lag of the groups reading them, purge, publish, and queries for groups and the latest records.
|
Package kafka reads and manages Kafka through its own protocol: topics with their sizes and the lag of the groups reading them, purge, publish, and queries for groups and the latest records. |
|
messaging/rabbitmq
Package rabbitmq reads and manages RabbitMQ through its management HTTP API (the management plugin).
|
Package rabbitmq reads and manages RabbitMQ through its management HTTP API (the management plugin). |
|
metrics/prometheus
Package prometheus reads metrics from anything that serves the Prometheus HTTP API: Prometheus, Thanos, Mimir, VictoriaMetrics, or an OpenTelemetry pipeline that ends in one of them.
|
Package prometheus reads metrics from anything that serves the Prometheus HTTP API: Prometheus, Thanos, Mimir, VictoriaMetrics, or an OpenTelemetry pipeline that ends in one of them. |
|
metrics/scrape
Package scrape is a metrics backend with no server: it scrapes the services' Prometheus or OpenTelemetry (Prometheus exporter) endpoints itself, keeps a short in-memory history, and answers a PromQL subset over it.
|
Package scrape is a metrics backend with no server: it scrapes the services' Prometheus or OpenTelemetry (Prometheus exporter) endpoints itself, keeps a short in-memory history, and answers a PromQL subset over it. |
|
profiler/command
Package command profiles with any tool you can run: async-profiler for the JVM, perf, py-spy, rbspy, dotnet-trace, ...
|
Package command profiles with any tool you can run: async-profiler for the JVM, perf, py-spy, rbspy, dotnet-trace, ... |
|
profiler/pprof
Package pprof captures Go profiles from a service's net/http/pprof endpoint, through the runtime's forwarding.
|
Package pprof captures Go profiles from a service's net/http/pprof endpoint, through the runtime's forwarding. |
|
query/http
Package http is a query component for HTTP APIs: "GET /path", "POST /path {json}".
|
Package http is a query component for HTTP APIs: "GET /path", "POST /path {json}". |
|
runtime/docker
Package docker runs each service as labelled containers on one network, so services reach each other by service name.
|
Package docker runs each service as labelled containers on one network, so services reach each other by service name. |
|
runtime/kind
Package kind is the Kubernetes runtime on a local kind cluster, plus what only kind can do: create and delete the cluster with a local registry, load images, and shell into nodes with docker.
|
Package kind is the Kubernetes runtime on a local kind cluster, plus what only kind can do: create and delete the cluster with a local registry, load images, and shell into nodes with docker. |
|
runtime/kubernetes
Package kubernetes runs services on a Kubernetes cluster through kubectl, so it uses whatever auth the user's kubeconfig has.
|
Package kubernetes runs services on a Kubernetes cluster through kubectl, so it uses whatever auth the user's kubeconfig has. |
|
runtime/local
Package local runs services as processes on this machine.
|
Package local runs services as processes on this machine. |
|
tracing/jaeger
Package jaeger reads traces through the Jaeger query API (Jaeger, or Grafana Tempo's Jaeger-compatible query).
|
Package jaeger reads traces through the Jaeger query API (Jaeger, or Grafana Tempo's Jaeger-compatible query). |
|
tracing/tempo
Package tempo reads traces through Grafana Tempo's own API: TraceQL search and OTLP traces.
|
Package tempo reads traces through Grafana Tempo's own API: TraceQL search and OTLP traces. |
|
tracing/zipkin
Package zipkin reads traces through the Zipkin v2 API (Zipkin itself, or anything compatible).
|
Package zipkin reads traces through the Zipkin v2 API (Zipkin itself, or anything compatible). |
|
Package ai puts an assistant inside rig without being one: every turn runs the user's own opencode or Claude Code, with rig's MCP server as its tools, the project directory as its only workspace, and rig's guard rails between it and the environments.
|
Package ai puts an assistant inside rig without being one: every turn runs the user's own opencode or Claude Code, with rig's MCP server as its tools, the project directory as its only workspace, and rig's guard rails between it and the environments. |
|
cmd
|
|
|
rig
command
|
|
|
Package core defines what every component kind must do.
|
Package core defines what every component kind must do. |
|
Package docs carries rig's reference into the binary: rig docs, and the rig_docs MCP tool.
|
Package docs carries rig's reference into the binary: rig docs, and the rig_docs MCP tool. |
|
Package engine ties a project to one environment: it builds components lazily from the plugin registry, resolves svc:// addresses through the runtime, and runs the multi-service operations (up, down, status) every front end shares.
|
Package engine ties a project to one environment: it builds components lazily from the plugin registry, resolves svc:// addresses through the runtime, and runs the multi-service operations (up, down, status) every front end shares. |
|
examples
|
|
|
hello
command
Command hello is the smallest rig example: one HTTP service with JSON logs and Prometheus metrics.
|
Command hello is the smallest rig example: one HTTP service with JSON logs and Prometheus metrics. |
|
internal/demo
Package demo is what the example services share: JSON logs, Prometheus metrics, Zipkin spans and pprof, with the standard library only, so each example's main.go is about its own work.
|
Package demo is what the example services share: JSON logs, Prometheus metrics, Zipkin spans and pprof, with the standard library only, so each example's main.go is about its own work. |
|
kind/app
command
Command app is the kind example's workload: one binary, two roles chosen by ROLE.
|
Command app is the kind example's workload: one binary, two roles chosen by ROLE. |
|
shop/app
command
Command app is the shop example's workload: one binary, two roles chosen by ROLE.
|
Command app is the shop example's workload: one binary, two roles chosen by ROLE. |
|
internal
|
|
|
cli
Package cli is rig's command line; every command is a thin layer over engine and the core interfaces.
|
Package cli is rig's command line; every command is a thin layer over engine and the core interfaces. |
|
httpx
Package httpx is the HTTP plumbing adapters share: base URLs from svc:// addresses, JSON calls with auth.
|
Package httpx is the HTTP plumbing adapters share: base URLs from svc:// addresses, JSON calls with auth. |
|
ide
Package ide writes the project's services into GoLand and VS Code, so they can be watched, stopped and debugged from the IDE while rig runs them.
|
Package ide writes the project's services into GoLand and VS Code, so they can be watched, stopped and debugged from the IDE while rig runs them. |
|
kubectx
Package kubectx picks the kubeconfig context an environment means.
|
Package kubectx picks the kubeconfig context an environment means. |
|
localhost
Package localhost describes this machine as a host and probes local HTTP endpoints; runtimes that run on this machine (local processes, docker) embed Host.
|
Package localhost describes this machine as a host and probes local HTTP endpoints; runtimes that run on this machine (local processes, docker) embed Host. |
|
scaffold
Package scaffold writes a first rig.yaml from what a directory already has: compose files, Kubernetes manifests, and services in Go, Python, Node, Java or Rust, plus infrastructure presets.
|
Package scaffold writes a first rig.yaml from what a directory already has: compose files, Kubernetes manifests, and services in Go, Python, Node, Java or Rust, plus infrastructure presets. |
|
sh
Package sh runs external tools (kubectl, docker, ssh, ...) with errors that carry their stderr.
|
Package sh runs external tools (kubectl, docker, ssh, ...) with errors that carry their stderr. |
|
traces
Package traces holds what every tracing adapter shares: summaries and the "traces" query language.
|
Package traces holds what every tracing adapter shares: summaries and the "traces" query language. |
|
tui
Package tui is rig's terminal control plane: one screen per concern (services, logs, metrics, traces, queries, key-value, data, load, manifests, hosts), all driven by the same engine as the CLI.
|
Package tui is rig's terminal control plane: one screen per concern (services, logs, metrics, traces, queries, key-value, data, load, manifests, hosts), all driven by the same engine as the CLI. |
|
tui/layoutgen
command
Command layoutgen writes layouts.go: for every non-Latin xkb layout on this machine, the rune each key gives, mapped back to the US key in the same place.
|
Command layoutgen writes layouts.go: for every non-Latin xkb layout on this machine, the rune each key gives, mapped back to the US key in the same place. |
|
viz
Package viz draws terminal charts: braille line charts with axes and legends, sparklines, gauges, and trace waterfalls.
|
Package viz draws terminal charts: braille line charts with axes and legends, sparklines, gauges, and trace waterfalls. |
|
Package manifest reads Kubernetes manifests from any folder layout, links the objects to each other (what selects, mounts, scales or routes to what), flags what is broken, and renders objects for apply.
|
Package manifest reads Kubernetes manifests from any folder layout, links the objects to each other (what selects, mounts, scales or routes to what), flags what is broken, and renders objects for apply. |
|
Package plugin is the adapter registry.
|
Package plugin is the adapter registry. |
|
sdk
module
|
|
|
Package skills carries the agent skills rig installs into a project (rig skill --install).
|
Package skills carries the agent skills rig installs into a project (rig skill --install). |
|
Package spec is the rig.yaml schema: services, environments and the components that serve them.
|
Package spec is the rig.yaml schema: services, environments and the components that serve them. |
Click to show internal directories.
Click to hide internal directories.