BETAv0.24.11
GitHub Install
Docs

Orrery docs

Orrery is a harness you install and shape at every level. Start with Install.

Start

  • Install Orrery has two parts you can install on their own:
  • Quickstart This page gets you from a fresh install to a first answer. It assumes orrery is on your PATH (Install).
  • Your first session A session is one conversation with the agent, stored on disk so you can come back to it.

Use

  • Sessions and resume Every conversation is a session: an append-only record of each prompt, each model reply and each tool call. Sessions are stored in the workspace's state directory, <workspace>/.orrery by default (--st
  • Providers and models A provider is where the model runs: a hosted API (Anthropic, OpenAI, Gemini), a local server (Ollama, vLLM) or any OpenAI-compatible endpoint. Each provider is an extension, and your build lists the o
  • config.toml and layers Configuration is the setup. Whatever a command, a flow or the UI configures is a key in a config.toml, and writing that key by hand does exactly the same thing. There is no hidden state: the only thin
  • Profiles A profile is a named bundle of settings: a model, extensions, MCP servers, skills, permissions, consent and environment. Two profiles from one binary are two different agents.
  • Permissions and consent Every tool call is checked by the policy engine before it runs, for every harness and every extension alike. Rules say what is allowed, what is denied, and what to ask you about.
  • The TUI and its keys Bare orrery at a terminal opens the TUI: a banner, the thread, a dock for questions, the input, and a footer with the permission mode, key hints, tokens, cost and model.
  • Orrery Cloud and your machines Orrery Cloud lists your machines and their sessions on every screen: the web, the ADE, the phone and orrery machines. A change on one shows on the others within about a second.

ADE

  • Agent mode The ADE is the Orrery desktop app. It has two modes, switched in the top bar: Agent mode and IDE mode.
  • IDE mode IDE mode runs any CLI agent in a terminal, on a worktree: Claude Code, Codex, pi, or orrery itself. Each one is a session in the sidebar, with its own branch, its terminal and an editor beside it.

Extend

  • Extensions Orrery is a harness you shape. Extensions are how: tools, model providers, commands, UI clients, MCP servers, memory and more. The built-in harness is made of the same parts anyone else gets. Most of
  • Install and manage One argument, in seven forms:
  • Write your first extension This page builds a small Node extension with one tool, tests it, and installs it. You need orrery and Node.js.
  • Manifest reference Every extension has an orrery.toml at its root. It is the contract: what the extension provides, what it asks for, and how it runs. Nothing outside it is available at runtime.
  • MCP servers Orrery speaks the Model Context Protocol. An existing MCP server works unmodified, behind the same policy check as every other tool.
  • Skills A skill is a SKILL.md file: front matter, then instructions the model reads when it needs them. Orrery takes the agentskills.io format unchanged, so a skill written for another agent works here as it
  • Clients A client is what draws a session: the terminal UI, the ADE's chat, a web page. In Orrery a client is an extension. The default terminal UI (ratatui) is one, installed by default; Ink is another; yours
  • Publish an extension There are two tiers: listed and verified.
  • The context API Every call between Orrery and an extension is in one list: harness/protocol/context-api.json. An extension asks the host for a service (a model, the session, a timer), or the host asks it to answer (a
  • Models and sessions An extension never holds a provider key. When it needs a model, it asks the host, and the host signs the request. What it gets back is the answer, the model that gave it, and the usage. The same goes
  • Input, timers and questions An extension can drive a run as a client does: send it input, keep it going with a driver, wake it with timers, and watch what it does. It can also ask the person a question, tell them something, and
  • Interceptors An interceptor is an extension's answer at one of five points in the loop: it can refuse a tool call, change its input or its result, shape the context, filter what memory returns, or change the reque
  • Context, compaction and memory Every pass, the harness builds what the model is sent: the system sections, the tool descriptions, the history, and the newest input. Each of the parts an extension may change has a core default that
  • Which tools the model sees The model is told every tool in its visible set in each prompt: the tools that exist, narrowed by the scope and by what policy would not deny. Every description costs tokens on every pass, so an exten
  • Show things: placements A placement is where a surface goes on the screen. The person places one with config or /ui, an extension with ui.show, and the agent with the ui.show tool. The client in use draws it with its own ele
  • Show things: components A component is a structure over the catalog orrery/1 plus one JSON object of data. The structure reads the data by JSON Pointer. The client binds the two and draws the result; no code of yours runs on
  • The catalog orrery/1 The catalog is every component type an extension, or the agent, can put in a structure (Show things: components). An extension composes these and never draws: a type the catalog lacks lives in a perso
  • Build your own client An extension never draws: it composes catalog components. When the catalog lacks something (a Gantt chart, a domain view), you build your own client: one of Orrery's terminal clients as a library, plu

Automate

  • One-shot runs orrery run -p "<prompt>" opens a session, takes one turn, prints the final text and exits. It is the form for scripts and CI.
  • serve and attach A kernel can run without a client, and any number of clients can attach to it: a second terminal, the ADE, a script.
  • The wire protocol A client talks to a kernel (orrery serve or a node) in two directions:
  • The SDK Install it from npm, at the version of the orrery you talk to:

Reference

  • CLI orrery --help is the map, and every subcommand has its own --help. With no subcommand, orrery starts an interactive session.
  • Config keys Every setting is a key in a config.toml (layers). Set one by hand or with orrery config set <dotted.key> <value>; orrery config explain <dotted.key> says where its value came from. A misspelt key in a
  • Environment variables A variable and the config key it stands for are the same setting. Where both exist, the variable wins for that one process.

Work safely

  • Workspace trust A repository can carry its own Orrery configuration: .orrery/config.toml, extensions, agents, skills, MCP servers. Those can run code. So a workspace nobody has vouched for does not load any of it.
  • Grants and the supply chain Installing an extension means running someone else's code. This page says what Orrery checks, and what it does not.