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: the core knows no technology. Docker, Kubernetes, SQL, Prometheus, GitLab, Jira and the rest are plugins, and anyone can write one: YAML, a shell script, or a Go, Python or TypeScript program, or any MCP server bridged in.
- 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.
How it is built
clients CLI · TUI · web UI (rig web) · MCP server · AI · HTTP/WS server (rig serve)
│ all through one api.Engine: policy, jobs and audit apply to every caller
kernel catalog · sources (data frames) · actions (jobs) · views (widget trees) · events · policy
engine environments, dependency order, up/down, svc:// resolution, run state
host install, lock, trust, supervisor, sandbox; talks to plugins over rig/1 (JSON-RPC)
plugins rig-std (docker, kubernetes, sql, prometheus, ...) · gitlab · jira · terraform · yours
A plugin adds sources (data), actions (verbs, each with an effect: read, write or danger),
views (tabs and panels), importers and contracts (metrics/1, scm/1, ...: implement one and
rig's own screens use your plugin). See design and plugins.
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). With Go 1.26+: go install github.com/goxang/rig/cmd/rig@latest.
rig itself knows no technology. Runtimes, builders, databases, metrics and the rest come from the
official plugins in goxang/rig-plugins, prebuilt: no Go needed.
The first rig in a project installs the ones its rig.yaml names (for you, in ~/.config/rig) and
the ones rig.lock pins (after one trust prompt). rig upgrade updates rig itself. To install the
everyday set by hand:
rig plugin add --user pack-std
A plugin that needs a token (Jira, Confluence, GitLab) shows it on its tab: press S there, or click
the banner, to paste the token; it is kept in ~/.config/rig, never in the repository.
Joining a project that already has a rig.yaml: run rig doctor there. It names each thing still
missing on your machine (plugins, workspace trust, a credential such as rig secret set JIRA_TOKEN)
with the command that fixes it; rig shows the same list when it opens.
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
rig web # the same control plane in the browser
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.
Plugins
rig plugin search jira # the registry index
rig plugin add pack/gitlab # install and pin in rig.lock
rig plugin ls # what the project uses, on or off
Official ones, a pack each: pack-std (local, docker, kubernetes, kind, go and command builders, git,
compose/godev imports), pack-data (sql, redis, rabbitmq, kafka, consul), pack-observability
(prometheus, scrape, loki, jaeger, tempo, zipkin, pprof, grafana), pack-qa (junit, pytest, jest,
vitest, hurl, k6, vegeta, ghz), pack-gitlab, pack-github, pack-atlassian (jira, confluence),
pack-cloud-aws (aws, terraform, helm, registry) and pack-product (agents that turn specs into
stories and MRs, every write waiting for approval). Plus slack, mcp-bridge, arcade, ssh,
delve, goland and importers for just, make, npm scripts, Procfile, dotenv, OpenAPI and CI files.
rig-std list prints them all.
Write your own:
rig plugin new sentry --lang yaml # or bash, python, go, ts
cd sentry && rig plugin test
cd ~/my-project && rig plugin dev ~/sentry
A plugin is a folder with a rig-plugin.yaml. If you can write rig.yaml, you can write one; add a
program only when YAML and shell are not enough. Plugins has the whole story, and
skills/rig-plugin lets an AI agent write one for you.
Docs
- Guide: CLI, every screen and its keys, AI, GoLand, agents
- Config: every
rig.yamlkey - CLI: every command
- Plugins: using and writing plugins; protocol, contracts, views
- Security: trust, sandbox, secrets, policy, server, audit
- Design: how rig is built
- Manifests: a manifest layout that works well with rig
All of it ships in the binary too: rig docs guide.
Contributing
New technology support goes into a plugin, not the core: goxang/rig-plugins
or your own repo. Fixes, screens and docs are welcome here. 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 |
|---|---|
|
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. |
|
agents
Package agents fires rig.yaml agents on their events and schedules.
|
Package agents fires rig.yaml agents on their events and schedules. |
|
router
Package router gives an AI a small fixed set of meta-tools over the Engine (find, call, query, read, open, skill, docs, file, ui) instead of one tool per action, so forty plugins do not flood its context.
|
Package router gives an AI a small fixed set of meta-tools over the Engine (find, call, query, read, open, skill, docs, file, ui) instead of one tool per action, so forty plugins do not flood its context. |
|
Package api is the Engine seam: CLI, TUI, MCP, the AI and the server are all clients of Engine.
|
Package api is the Engine seam: CLI, TUI, MCP, the AI and the server are all clients of Engine. |
|
cmd
|
|
|
rig
command
|
|
|
Package contracts holds rig's contracts: the named sources and actions a plugin provides to stand in for a kind of tool (metrics/1, scm/1, ...), with their arguments and frame fields, a conformance check, bridges that let a plugin serve rig's built-in screens, and standard views.
|
Package contracts holds rig's contracts: the named sources and actions a plugin provides to stand in for a kind of tool (metrics/1, scm/1, ...), with their arguments and frame fields, a conformance check, bridges that let a plugin serve rig's built-in screens, and standard views. |
|
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. |
|
Package host finds, starts and supervises plugins, and connects them to the engine.
|
Package host finds, starts and supervises plugins, and connects them to the engine. |
|
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. |
|
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. |
|
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. |
|
sign
command
Command sign writes file.minisig for each file, signed with $RIG_SIGNING_KEY; the release job runs it.
|
Command sign writes file.minisig for each file, signed with $RIG_SIGNING_KEY; the release job runs it. |
|
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. |
|
web
Package web is `rig web`: the control plane in a browser, served on this machine.
|
Package web is `rig web`: the control plane in a browser, served on this machine. |
|
kernel
|
|
|
actions
Package actions runs named verbs: each goes through policy, runs as a job and, unless it only reads, lands in the audit log.
|
Package actions runs named verbs: each goes through policy, runs as a job and, unless it only reads, lands in the audit log. |
|
audit
Package audit appends every write to a JSONL log, secrets redacted.
|
Package audit appends every write to a JSONL log, secrets redacted. |
|
cache
Package cache keeps source answers for their TTL and runs one fetch per key at a time.
|
Package cache keeps source answers for their TTL and runs one fetch per key at a time. |
|
catalog
Package catalog lists what a project has, as typed resources: core kinds from rig.yaml and kinds plugins add, such as terraform.stack.
|
Package catalog lists what a project has, as typed resources: core kinds from rig.yaml and kinds plugins add, such as terraform.stack. |
|
config
Package config composes a project's configuration from its layers and remembers where each value came from.
|
Package config composes a project's configuration from its layers and remembers where each value came from. |
|
cron
Package cron reads 5-field cron schedules.
|
Package cron reads 5-field cron schedules. |
|
events
Package events is the bus: plugins, the engine and agents publish typed events such as deploy.finished, and hooks subscribe by topic pattern.
|
Package events is the bus: plugins, the engine and agents publish typed events such as deploy.finished, and hooks subscribe by topic pattern. |
|
frames
Package frames reads and builds protocol frames: columnar, typed rows.
|
Package frames reads and builds protocol frames: columnar, typed rows. |
|
identity
Package identity says who is calling: a person, the AI, an agent or an API token.
|
Package identity says who is calling: a person, the AI, an agent or an API token. |
|
inbox
Package inbox keeps writes waiting for another person's approval, one JSON file each, with the plan of what they would do.
|
Package inbox keeps writes waiting for another person's approval, one JSON file each, with the plan of what they would do. |
|
jobs
Package jobs keeps the operations a session runs (a build, a deploy, a task, a plugin action): their output, progress and end, for any renderer to show while they run and after.
|
Package jobs keeps the operations a session runs (a build, a deploy, a task, a plugin action): their output, progress and end, for any renderer to show while they run and after. |
|
policy
Package policy decides whether a subject may run an action: allow, deny, confirm (the same person again), reauth (password or TOTP again) or approve (another person).
|
Package policy decides whether a subject may run an action: allow, deny, confirm (the same person again), reauth (password or TOTP again) or approve (another person). |
|
refs
Package refs handles the URIs every resource and row can carry, such as svc://api or jira://PAY-12.
|
Package refs handles the URIs every resource and row can carry, such as svc://api or jira://PAY-12. |
|
view
Package view turns view specs into renderer-neutral widget trees, fetches the frames widgets bind to and transforms them.
|
Package view turns view specs into renderer-neutral widget trees, fetches the frames widgets bind to and transforms them. |
|
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 in-process adapter registry.
|
Package plugin is the in-process adapter registry. |
|
Package protocol is rig/1, the plugin protocol: its schema, the types generated from it, and a validator.
|
Package protocol is rig/1, the plugin protocol: its schema, the types generated from it, and a validator. |
|
conformance
Package conformance checks a plugin speaks rig/1: what every plugin must do, and what each capability it declares promises.
|
Package conformance checks a plugin speaks rig/1: what every plugin must do, and what each capability it declares promises. |
|
rpc
Package rpc is the host's end of rig/1: newline-delimited JSON-RPC 2.0 to one plugin process.
|
Package rpc is the host's end of rig/1: newline-delimited JSON-RPC 2.0 to one plugin process. |
|
transcript
Package transcript records and replays rig/1 sessions as JSONL: one {"dir":">","msg":{...}} per message, ">" from the host to the plugin and "<" back.
|
Package transcript records and replays rig/1 sessions as JSONL: one {"dir":">","msg":{...}} per message, ">" from the host to the plugin and "<" back. |
|
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. |
|
sdk
module
|
|
|
Package server is `rig serve`: the Engine API over HTTPS for remote CLIs, MCP clients and the web inbox, with accounts, server-side policy, reauth, approvals, leases and one audit log per environment.
|
Package server is `rig serve`: the Engine API over HTTPS for remote CLIs, MCP clients and the web inbox, with accounts, server-side policy, reauth, approvals, leases and one audit log per environment. |
|
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.