Install and manage · Orrery docs

Install

orrery install <source>

One argument, in seven forms:

Form	Installs from	Pinned
`buildgraph` · `buildgraph@1.2.0`	A signed registry index.	Yes
`github:owner/repo` · `…#tag` · `…#sha`	A git host. Only a `sha` is reproducible.	No
`https://host/repo.git`	Any git URL.	No
`crate:orrery-ext-x` (also `crates-io:`)	crates.io.	No
`npm:@scope/orrery-ext-x`	npm.	No
`./path` · `../path` · `file:path` · `/abs/path`	A local folder.	No
`./path --link`	A symlink to a local folder, for development.	No

The registry is how you trust an extension; the other sources are how you try one. A bare name resolves through a signed index that pins a sha256 and lists what the extension asks for. Every other source installs pinned: false, and says so in the ledger.

A bare name resolves against the first index it finds: --index <path>, then [registry] index in the managed layer, then in your user layer, then Orrery's public index, https://getorrery.dev/registry/index.toml. A URL is fetched by orrery install itself; its signature is checked before the document is read, the copy is cached, and the fetch is recorded in the audit stream. A managed [registry] public = false turns the public index off.

Not live yet: Orrery's public index has no signing key and no entries yet, so a bare name with no index of your own fails and says why. Until it is live, install community extensions by source (npm:, crate:, github:).

Flags

Flag	Meaning
`--to user\|workspace`	Which layer. `user` (`~/.orrery/extensions/`) by default.
`--user`	Same as `--to user`.
`--link`	Symlink a local folder instead of copying it.
`--yes`	Grant everything the extension asks for, without asking.
`--force`	Replace an existing install.
`--index <path>`	A signed index file to resolve bare names against.

Grants

Installing shows what the extension asks for, as a list of capabilities:

 buildgraph 1.2.0 requests:
   read     $WORKSPACE/**
   spawn    java

A request you do not grant is denied, and the extension installs anyway with less: the tools that need it are disabled, and the ledger records degraded. Without a terminal, requests are denied by default; pass --yes to grant them.

On an upgrade, a capability the old version did not ask for is marked new and defaults to deny.

Remove

orrery remove buildgraph
orrery remove buildgraph --from workspace

When it is installed at both layers, remove asks which instead of guessing.

Inspect

orrery ext list                  # every extension: where it comes from (FROM), its process, state and memory
orrery ext show buildgraph       # its folder, the copy it shadows, its tools, commands and state
orrery ext test ./my-extension   # run its tests against the mock broker

Extensions load from ~/.orrery/extensions (FROM user) and the project's .orrery/extensions (workspace). Both are listed; for one id the workspace copy is used, and the user copy it hides is listed as shadowed right under it. ext list reads what each offers from the cache filled at install, so listing starts nothing; ext test actually starts one.

In a session

/mcp and /skills add and remove MCP servers and skills from the TUI. A change applies from the next turn.

When an organisation pins versions

Under a managed [registry] unpinned = "refuse", every unpinned source is refused, and the ledger says why. See Grants and the supply chain.

Install and manage extensions

#Install

#Flags

#Grants

#Remove

#Inspect

#In a session

#When an organisation pins versions