Rig

Rig is a declarative description and manager of a person's working setup. It gives tools, agent skills, managed resources, and private port allocations one understandable catalogue, then compares that declared intent with the machine in front of you.

Rig answers questions such as:

• What is in my setup, and why did I choose it?
• Which parts belong on this machine or in this role?
• Which native system installs or observes each part?
• What is present, missing, drifted, unavailable, or unknown?
• Which deliberately public subset can I publish without exposing machine state?

Rig coordinates native systems rather than replacing them. Homebrew, uv, mise, npm, chezmoi, launchd, macOS defaults, and trusted extensions keep their own manifests, resolution rules, credentials, and state.

The model

• A catalogue records the identity, purpose, rationale, relationships, and supported platforms of each tool.
• A skill records a user-level agent capability and the native authority responsible for it.
• A managed resource records desired services, scheduled jobs, typed machine settings, and semantic layouts.
• A private port records stable TCP intent without opening, reserving, or publishing a socket.
• A profile selects a complete machine or role setup, or a non-appliable view such as a public subset.
• A provider is the native system that materialises or observes declared intent.
• State is Rig's comparison between a resolved profile and provider observations on the current machine.

That makes Rig a manager of managers beneath a catalogue people can read.

Install

Rig is a pre-v1 public preview. The latest immutable release is v0.3.0:

curl -fsSL https://raw.githubusercontent.com/knowledgeislands/tools-rig/v0.3.0/install.sh | bash -s -- v0.3.0

That command installs the released 0.3.0 contract.

To use the current checkout while developing or evaluating those changes, link both the executable and manual:

./install.sh --link
rig --version # rig 0.3.0

The final version identifies the selected release candidate.

Start here

Follow Get started with Rig to write a small human-readable configuration, inspect it, check the machine, and preview the first application.

The user-guide journey then introduces profiles, machine resources, user-level skills, provider boundaries, and publication in stages. Use man rig for the exhaustive command and configuration reference.

Documentation

• User guides explain how to adopt and operate Rig.
• Developer guides explain how to change and release Rig.
• Decision Records explain durable architectural choices.
• Specifications define accepted, testable behaviour.
• Roadmap identifies canonical forward work.

Contributing

Issues and pull requests are welcome. Start with Develop Rig and use the definition of done before presenting a change for review.

License

MIT © 2026 Kris Brown.