Managing ribs

Ribs are how the harness gains capability: separately versioned packages that register tools, workflows, and surfaces through a typed contract. Keelson keeps no registry of which ribs exist, so installing one is dependency management, not integration work. What follows is the operator’s reference for the rib lifecycle: install, inspect, activate, update, remove.

Install

keelson rib add hands your source to bun and installs into the managed home. Any bun-installable source works:

Source form	Example
GitHub URL	https://github.com/danielscholl/keelson-rib-beads
GitHub shorthand	github:you/keelson-rib-yours
Git URL	git@github.com:you/keelson-rib-yours.git
npm package	@keelson/rib-yours
Local path	./keelson-rib-yours

keelson rib add https://github.com/danielscholl/keelson-rib-beads

A rib installed from a git source is pinned to that repository’s newest release tag, and the command reports which one it took. Pass --ref <ref> to install a branch or a commit instead, which is what rib development wants:

keelson rib add https://github.com/danielscholl/keelson-rib-swarm --ref main

Discovery happens once, at boot, so a rib installed while the server is running is not active until the next restart. The command reports restartRequired: true when that is the case.

A rib is code you choose to run

Installing a rib executes someone else’s package inside your harness, with the same access to your machine as any dependency. The namespace and credential rules guard against collisions and cross-rib reads; they are not a sandbox. Install ribs from sources you trust.

Inspect

keelson rib list --installed     # reads the home directly; no server needed
keelson rib list                 # discovered + active, with tools and surfaces (server-required)
keelson rib show <id>            # one rib's tools, views, surfaces, and auth (server-required)
keelson rib reload               # re-collect unbound workflows without a restart (server-required)

rib show is the inspection tool: it reports the tools the rib registered, the views and surfaces it declared, whether it handles board actions, and its auth status if it declares a probe. The same inventory backs the browser UI, where an installed rib appears as a top-level tab with its tools on tap in Chat.

Activate

Installed and active are distinct states. KEELSON_RIBS is the operator’s filter between them, applied per process:

KEELSON_RIBS=beads keelson start      # activate only beads
keelson start                         # unset: activate everything discovered

This makes experiments cheap: keep several ribs installed and activate one. A rib that fails validation at boot is skipped with a single warning in the log, never a crash, so the boot log is the audit trail for what activated and what did not.

Active is still not the same as connected. Two ribs that are both installed and both active cannot call each other’s tools: crossing that line is default-deny, and you grant it per caller → target → tool with crossRibGrants in config.json. This is the first thing a second rib runs into, and the denial is quiet, so reach for cross-rib grants when a rib seems to be missing a capability you expected it to have.

Update

Ribs move release to release, the same way the harness does. Every git-sourced rib is held at an explicit release tag in the home’s manifest, so nothing advances it until you ask.

keelson update                        # the harness and every rib, together
keelson rib update                    # only the ribs
keelson rib update swarm              # only one
keelson rib update --check            # report what is available, apply nothing
keelson rib update swarm --to 0.24.0  # an exact version, including older ones

Releases are read with git ls-remote, so resolution works on any git host, needs no forge API token, and has no rate limit to spend across a multi-rib update.

A rib you pinned to a branch or a commit with --ref is left alone by both commands, and reported as tracking that ref. --to is the way to move it back onto a release.

Two outcomes are deliberately kept apart. A rib whose repository has no release tags yet is reported and left where it is. A rib whose repository could not be read at all is reported by name, and the command exits non-zero rather than letting an unchecked rib pass for one that is current.

An installed rib stays a managed dependency that advances with the harness, not a fork you maintain.

Ribs declare the harness they need

A rib’s package manifest carries the @keelson/shared range it was built against. After an update, keelson compares that range to the harness in your home and warns whenever the harness does not satisfy it, in either direction, naming the rollback command. That rib would otherwise be skipped at boot with only a line in the server log.

Remove

keelson rib remove swarm       # by rib id

Related

• The rib model: why capabilities are packages and the boundary the harness enforces.
• The Rib contract: the precise interface a rib implements.
• Governance: granting one rib access to another’s tools, and the rest of the policy engine.