Orion Docs

Introduction

Orion is an open-source AI coding agent that runs in your terminal and uses a model you choose, paid for with your own API key.

You describe a task in plain language, for example “add a dark mode toggle to the navbar”. Orion sends the request to your model together with a set of tools. The model decides which tools to call: it lists folders, reads files, searches the code, edits files and runs commands such as your tests. Orion runs each tool on your computer, sends the result back, and repeats until the task is done.

How it differs from hosted tools

• Your key, your bill. Orion never sells model access. Requests go straight from your computer to the provider you configured.
• Any provider. Anthropic, OpenAI, OpenRouter, Google Gemini, Groq, DeepSeek, xAI, local models through Ollama or LM Studio, and any server with an OpenAI-compatible API.
• Agents you write yourself. An agent is a Markdown file with its own model, tools and instructions.
• You approve changes. By default Orion asks before it writes a file or runs a command, and it cannot touch files outside your project folder.

Installation

Orion runs on macOS, Windows and Linux. Pick whichever install method you already use; they all give you the same orion command.

Two kinds of install

• Standalone program (install script). One self-contained file. Nothing else to install, not even Node.js.
• npm package (npm, pnpm, yarn, bun). Small download, but needs Node.js 18 or newer. Check with node -v.

Either way you also need an API key from at least one provider, or a local model server such as Ollama.

macOS and Linux

curl -fsSL https://orionrh.xyz/install.sh | sh

If curl isn’t installed, use wget -qO- https://orionrh.xyz/install.sh | sh. The script:

• Detects your system and CPU: Intel or Apple Silicon Macs, x86-64 or ARM64 Linux, and glibc or musl (Alpine) distributions.
• Downloads the matching build from orionrh.xyz and checks its SHA-256 checksum.
• Installs orion into ~/.orion/bin without sudo, and adds that folder to your PATH in .bashrc, .zshrc, .profile and fish.

It works on Ubuntu, Debian, Kali Linux, Parrot OS, Fedora, Rocky Linux, Arch Linux, openSUSE, Alpine and macOS, and on distributions built on them such as Linux Mint, Pop!_OS and Manjaro.

Windows

In PowerShell:

irm https://orionrh.xyz/install.ps1 | iex

Installs orion.exe into %USERPROFILE%\.orion\bin and adds it to your user PATH. No administrator rights needed. Windows on ARM runs the x64 build through Windows’ built-in emulation. Open a new terminal afterwards so the new PATH is picked up.

Package managers

Manual download

Every release has these files. Unpack one and put orion (or orion.exe) anywhere on your PATH.

32-bit systems are not supported by the standalone builds; use the npm package there.

Install script options

curl -fsSL https://orionrh.xyz/install.sh | ORION_VERSION=0.1.0 sh

Check it works

orion --version

This should print 0.1.0. If the command isn’t found, open a new terminal.

Update

Run the same install command again, or use your package manager: npm update -g orionrh.

Uninstall

Uninstalling leaves your settings and keys in ~/.orion. Delete that folder to remove them too.

Quickstart

From install to your first change in about a minute.

1. Connect a provider. Run the setup and follow the prompts.
   shell

   orion login

2. Open a project. Orion works in the folder you start it from.
   shell

   cd ~/projects/my-app

3. Start a session.
   shell

   orion

4. Describe the task. Type what you want and press Enter. Approve each edit or command when asked.

A typical session looks like this:

  agent build · model anthropic/claude-opus-5-5 · ~/projects/my-app

› add a dark mode toggle to the navbar
● read_file src/components/Navbar.tsx
● read_file src/styles/theme.css

? Edit src/components/Navbar.tsx
    - <nav className="navbar">
    + <nav className="navbar" data-theme={theme}>
  Allow? [y]es / [n]o / [a]lways this session: y
● run_command npm test
Added the toggle and saved the choice in localStorage. All tests pass.

Connecting a provider

Run orion login once for each provider you want to use.

What orion login does

1. Shows the list of built-in providers, plus custom for any other OpenAI-compatible API. Type the number and press Enter.
2. Asks for your API key. Input is hidden while you type. Leave it empty to use the provider’s environment variable instead.
3. Tests the connection by fetching the provider’s model list. If that fails, it shows the error and asks whether to save anyway.
4. Shows up to 25 models and asks for a default. Press Enter to accept the suggestion in brackets.
5. Saves everything to ~/.orion/config.json.

Built-in providers

For Anthropic, the suggested default model is claude-opus-5-5.

Using environment variables instead

If the variable for a built-in provider is set, Orion uses it whenever no key is saved for that provider. You don’t need to run orion login at all, but you do need a default model:

# macOS / Linux
export ANTHROPIC_API_KEY="sk-ant-..."
orion use anthropic/claude-opus-5-5

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-..."
orion use anthropic/claude-opus-5-5

A key saved with orion login takes priority over the environment variable.

Removing a provider

orion logout openai

This deletes the saved entry. If your default model used that provider, the default is cleared and you’ll need to pick a new one with orion use.

Local models

Run models on your own computer for free, without sending code to a cloud provider.

Ollama

1. Install Ollama from ollama.com and start it. It listens on port 11434.
2. Download a model that supports tool calling (function calling). Check the model’s page to confirm.
   shell

   ollama pull <model-name>

3. Run orion login, choose ollama and pick the model. No key is asked for.

LM Studio

1. Download a model in LM Studio.
2. Open the Developer tab and start the local server. It listens on port 1234.
3. Run orion login and choose lmstudio.

Custom providers

Any API that follows the OpenAI chat completions format works, including Together, Fireworks, Mistral, a company proxy or your own server.

With orion login

Choose custom, then enter a short name (letters, numbers, - and _), the base URL and, if the server needs one, an API key.

By editing the config

{
  "model": "together/meta-llama/Llama-3.3-70B-Instruct-Turbo",
  "providers": {
    "together": {
      "type": "openai",
      "baseURL": "https://api.together.xyz/v1",
      "apiKey": "..."
    }
  }
}

You can also override a built-in provider this way, for example to send openai requests through a proxy by giving it a different baseURL.

Choosing a model

Models are always written as provider/model-id.

Orion splits at the first slash, so model IDs that contain slashes work as expected: in openrouter/anthropic/claude-sonnet-5-5 the provider is openrouter and the model is anthropic/claude-sonnet-5-5.

See what you can use

orion models            # every configured provider
orion models openrouter # one provider

Your current default is marked with ●.

Ways to pick a model

Which one wins

When more than one is set, Orion uses the first of these that exists:

1. The -m flag, or a model chosen with /model during the session.
2. The model in the active agent’s file.
3. The model in your configuration.

Thinking effort for Claude models

For the anthropic provider you can set how much effort the model spends on each step. Lower is faster and cheaper; higher is more thorough.

{ "effort": "high" }

Accepted values are low, medium, high, xhigh and max. Leave it out to use the model’s default. Other providers ignore this setting.

Sessions and one-off tasks

Use an interactive session for back-and-forth work, or orion run for a single task.

Interactive session

orion

Orion shows the active agent, model and folder, then waits at the › prompt. The conversation keeps its history until you clear it, switch model or agent, or exit. Exit with /exit, Ctrl+D or Ctrl+C.

One-off task

orion run "rename the getUser function to fetchUser everywhere"

Orion does the task, prints the result and exits. The exit code is 1 if the model request failed, so it can be used in scripts. If nothing can answer the permission prompts (for example in CI, where there is no terminal), writes and commands set to ask are refused. Use --yolo or set permissions to allow for unattended runs.

Options

Long tasks

A single request can take up to 60 tool steps. If a task needs more, Orion stops and tells you. Type continue to carry on from where it stopped.

Session commands

Type these at the › prompt during an interactive session.

Tools

These are the actions the model can take. Paths are always relative to the folder you started Orion in.

Details

• Ignored folders. list_dir, find_files and search skip .git, node_modules, dist, build, .next, .venv, venv, __pycache__, .cache and coverage.
• Long output from any tool is cut at 20,000 characters, with a note saying how much was left out.
• Shell. Commands run in cmd.exe on Windows and /bin/sh on macOS and Linux, with your normal environment variables.
• Commands that wait for input, such as a dev server or an interactive prompt, will run until the 2-minute limit. Ask the model to use non-interactive flags, or start long-running servers yourself.

Permissions and safety

Orion separates actions into two kinds you can control: write (write_file, edit_file) and bash (run_command). Reading and searching never ask.

Answering a prompt

Setting defaults

{
  "permission": { "write": "ask", "bash": "ask" }
}

Each can be ask (the default), allow or deny. For example, {"write": "allow", "bash": "ask"} lets Orion edit freely but still checks every command.

Skipping prompts

--yolo sets both kinds to allow for that run. In a session, /yolo turns it on or off.

What Orion will not do

• File tools refuse any path outside the project folder, including .. and absolute paths.
• The plan agent and any custom agent without write tools cannot change files, whatever your permission settings.

Agents

An agent is a model plus a set of tools plus instructions. Orion ships with two.

Switching agents

orion -a plan          # start with an agent
orion agents           # list every agent and where it comes from

Inside a session, use /agent plan. To change the default agent, set "agent": "plan" in your configuration.

A good pattern for larger changes: ask plan for a plan, read it, then switch to build and ask it to carry the plan out.

Writing a custom agent

Create a Markdown file. The file name is the agent’s name.

Where to put it

If both exist with the same name, the project one is used. A file named build.md or plan.md replaces the built-in agent.

File format

---
description: Reviews code for bugs and security problems
model: openrouter/your-model
tools: read_file, search, find_files, list_dir
---
You are a senior engineer reviewing this project.
Point out bugs, security problems and unclear code, with file and line.
Do not modify any files. End with a short summary of the most important issues.

The header block between the --- lines is optional. Everything after it is added to Orion’s instructions for that agent.

More examples

---
description: Writes and fixes tests
tools: list_dir, read_file, find_files, search, write_file, edit_file, run_command
---
Write tests for the code the user names. Match the existing test style and
framework. Run the test command after every change and fix failures.
Never change application code, only test files.

---
description: Writes and updates documentation
tools: list_dir, read_file, find_files, search, write_file, edit_file
---
Keep README files and code comments accurate and short. Read the code before
describing it. Never run commands.

Project instructions

Tell Orion about your project once, instead of repeating it in every request.

Create ORION.md in the folder where you run Orion. Its contents are added to the instructions of every agent in every session. If there is no ORION.md, Orion reads AGENTS.md instead, so a file you already keep for other tools works too.

# My App

Next.js 15 with TypeScript, Tailwind and Prisma.

## Commands
- Install: npm install
- Test: npm test
- Lint: npm run lint

## Rules
- Use server components unless a component needs state.
- Put shared types in src/types.
- Never edit files in src/generated.

Good things to include: the stack, the commands to build, test and lint, folder conventions, and anything the agent must never touch. Keep it short; it is sent with every request.

Configuration file

Orion keeps its settings in ~/.orion/config.json. Most people never edit it by hand.

Full example

{
  "model": "anthropic/claude-opus-5-5",
  "agent": "build",
  "effort": "high",
  "permission": { "write": "ask", "bash": "ask" },
  "providers": {
    "anthropic": { "apiKey": "sk-ant-..." },
    "ollama": {},
    "together": { "type": "openai", "baseURL": "https://api.together.xyz/v1", "apiKey": "..." }
  }
}

Per-project settings

A project can override settings in .orion/config.json inside the project folder. Top-level keys replace the global ones; permission and providers are merged key by key.

{
  "model": "ollama/your-local-model",
  "permission": { "bash": "deny" }
}

Viewing your settings

orion config

Prints the file’s location and the combined settings for the current folder, with keys shortened so they are safe to share. On macOS and Linux the file is created readable only by your user.

CLI reference

Options -m, -a and --yolo work with orion and orion run, before or after the task. An unknown command is an error, so a typo such as orion lgoin never gets sent to the model as a task.

Environment variables

Troubleshooting

No model set yet. Run "orion login"

No default model is saved and none was passed with -m. Run orion login, or orion use provider/model if your key is already set.

No API key for "openai"

That provider has no saved key and its environment variable is empty. Run orion login and choose it, or set the variable in the same terminal before starting Orion.

401 Unauthorized — the API key was rejected

The key is wrong, expired or revoked, or belongs to a different provider. Create a new key in the provider’s dashboard and run orion login again. Also check that the account has billing set up; some providers reject keys on accounts without credit.

Could not connect (127.0.0.1:11434)

The local server isn’t running. Start Ollama or the LM Studio server, then try again. For a custom provider, check the baseURL.

Unknown provider "x"

The part of the model name before the first slash doesn’t match any built-in or saved provider. Check spelling with orion config.

The model answers but never edits files

The model probably doesn’t support tool calling, or you are using the plan agent. Check with /agent, and pick a model whose provider lists tool or function calling support.

old_string found 0 times

The model tried to edit text that isn’t in the file, usually because the file changed. This is normal; the model sees the error, reads the file again and retries.

Stopped after 60 steps

The task hit the step limit for one request. Type continue, or split the task into smaller requests.

Response was cut off mid tool call

The model tried to write a very large file in one go and hit its output limit. Ask it to make the change in smaller parts.

The model declined this request

The provider’s safety system refused the request. Rephrase it with more context about what you are building.

FAQ

Does Orion see or store my API key anywhere else?

No. The key is stored in ~/.orion/config.json on your computer, or read from your environment, and sent only to the provider you configured. There is no Orion server.

What does it cost?

Orion is free and open source. You pay your model provider for the tokens you use, at their normal rates, or nothing at all with a local model. Check token use with /usage.

Where does my code go?

The files the model reads and the output of commands are sent to your model provider as part of the conversation. With Ollama or LM Studio, nothing leaves your computer.

Which model should I use?

For real coding work, a strong model with good tool calling gives the best results. Use a cheaper or local model for small edits, reviews and questions; agents can each have their own model, so you can mix them.

Can I use it without internet?

Yes, with a local model through Ollama or LM Studio.

Does it work on Windows?

Yes. Commands run in cmd.exe, so the model needs to use Windows commands; Orion tells it which platform it is on.

How is $ORION related to the tool?

$ORION is the project’s community token. You don’t need it to use Orion. See the home page for details. It has no intrinsic value and nothing here is financial advice.