# OpenAgents > OpenAgents is an open network of agents you work with through one conversation, from anywhere: this website, your phone, or a terminal. --- Source: https://openagents.com/docs/what-is-openagents # What is OpenAgents OpenAgents is an open network of agents you work with through one conversation, from anywhere: this website, your phone, or a terminal. Ask a question, plan some work, or ask for a code change, and each message goes to whichever agent, model, or computer in the network serves it best. ## What you can do with it - **Chat.** Ask about OpenAgents, about your project, or about anything else. Many answers come at once from our prepared answers and product notes. See [Chat](/docs/chat). - **Hand work to Coder.** When a message is coding work, Coder, our coding agent, does it on your own computer, with the coding agents you already use there: Codex, Claude Code, Grok Build, OpenCode, or Devin CLI. See [Coder](/docs/coder). - **Add plugins.** A plugin is anything you add to OpenAgents. You can make one, test whether it helps Coder, and publish the result so other people can check it. See [Plugins](/docs/plugins). - **Earn XP in the Gym.** Checking other people's results and having your plugin adopted earns XP. See [The Gym and XP](/docs/gym-and-xp). ## One chat, every surface | Where | What it is | | --- | --- | | [openagents.com](/docs/website) | Start a chat from the homepage. | | [OpenAgents for Mac](/docs/mac) | Chats, Coder on your Mac, the Verse, the Map, and decks. It also connects your phone to your Mac. | | [OpenAgents for iPhone](/docs/iphone) | Chats, Coder on your computers, the Verse, and a bitcoin wallet. | | [Coder](/docs/coder) | A coding agent in your terminal: run `coder` in any project folder. | | [OpenAgents Terminal](/docs/terminal) | The same chat full screen in a terminal, with Coder in the folder you start from. | | [The `openagents` command](/docs/cli) | Chat, settings, plugins, and pairing from a shell or a script. | On a computer, your chats are the same chats in the Mac app, the Terminal, and the `openagents` command, and a phone connected to that computer sees them too. ## Open, all the way down OpenAgents runs on open protocols: messages, results, and XP are signed records on Nostr, an open network of relays. The app, the chat service, Coder, and the protocols are open source at [github.com/OpenAgentsInc/openagents](https://github.com/OpenAgentsInc/openagents), under the Apache License 2.0. The apps need no account or password: each device makes its own key the first time it runs. Why we built it this way is in two essays: [The Return of the General Agent](https://github.com/OpenAgentsInc/openagents/blob/main/docs/essays/2026-10-01-the-return-of-the-general-agent.md) and [Test-Time Capabilities](https://github.com/OpenAgentsInc/openagents/blob/main/docs/essays/2026-09-29-test-time-capabilities.md). Next: [Download](/docs/download). --- Source: https://openagents.com/docs/download # Download and install Coder runs on macOS, Linux, and Windows. One command installs it, and the same command updates it. The [download page](/download) has the same commands and a manual download for each platform. ## Install Coder On macOS or Linux, in a terminal: ```sh curl -fsSL https://openagents.com/cli/install.sh | bash ``` On Windows, in PowerShell: ```powershell irm https://openagents.com/cli/install.ps1 | iex ``` Then open a new terminal and check it: ```sh coder --version ``` It prints `coder` and the version you have. The installer picks the latest release for your computer: Apple silicon or Intel on macOS, x86_64 or ARM on Linux (including musl systems such as Alpine), and x86_64 on Windows (Windows on ARM runs that build too). Next, sign in and send a first message: [Coder quick start](/docs/coder). ## What gets installed | Command | What it is | | --- | --- | | `coder` | The Coder terminal app. Run it in a project folder. | | `openagents` | The OpenAgents command: Coder from scripts, chat, settings, and more. See [The openagents command](/docs/cli). | | The engine | The engine Coder's own coding loop runs on. You never run it yourself. | On Windows there is a fourth file, `coder-boundary.exe`, which keeps the commands Coder runs from writing outside the folders they're given. They go in `~/.openagents/bin` (on Windows, `%USERPROFILE%\.openagents\bin`). The installer adds that folder to your `PATH`: on macOS and Linux it adds one line to your shell's startup file (`.zshrc`, `.bashrc`, `.bash_profile`, `config.fish`, or `.profile`), and on Windows to your user `PATH`. Open a new terminal to pick it up. Before anything is replaced, the installer checks each download against the release's published SHA-256 checksums and checks that each command runs and reports the right version. If any step fails, your existing install is left as it was. ### Install options ```sh # One exact version curl -fsSL https://openagents.com/cli/install.sh | bash -s -- 1.0.0 # Follow release candidates curl -fsSL https://openagents.com/cli/install.sh | bash -s -- rc # Another folder, and no change to your shell's startup file curl -fsSL https://openagents.com/cli/install.sh | CODER_BIN_DIR=~/bin CODER_NO_PATH_UPDATE=1 bash ``` On Windows, set the same choices first: ```powershell $env:CODER_VERSION = '1.0.0' # or: $env:CODER_CHANNEL = 'rc' irm https://openagents.com/cli/install.ps1 | iex ``` With no version named, the installer follows stable releases, and the newest release candidate while no stable release is out yet. ## Update Coder keeps itself up to date. Once a day, while it's open, it checks for a newer release, downloads and verifies it in the background, and installs it when you quit. A release candidate follows release candidates; a stable release follows stable releases. | To | Run | | --- | --- | | Update now | `coder update` | | Just check | `coder update --check` | | Go back to the version the last update replaced | `coder update --rollback` | | Only be told when an update is ready | `coder update --mode notify` | | Stop checking | `coder update --mode off` | | Switch to release candidates | `coder update --channel rc` | Running the install command again also updates Coder. ## Uninstall 1. Sign this computer out of your account: `coder logout`. 2. Remove the install folder, where the installer put Coder's commands and the copies kept for `coder update --rollback` (keep anything else you put there yourself). On macOS or Linux: ```sh rm -rf ~/.openagents/bin ``` On Windows, in PowerShell: ```powershell Remove-Item -Recurse "$env:USERPROFILE\.openagents\bin" ``` 3. Remove the `PATH` line. On macOS and Linux, delete the two lines that start with `# Coder installer PATH` from your shell's startup file. On Windows, remove `.openagents\bin` from your user `PATH` in **Settings → System → About → Advanced system settings → Environment Variables**. 4. To also delete your saved chats and Coder's settings on this computer: `rm -rf ~/.openagents/coder` (on Windows, `Remove-Item -Recurse "$env:USERPROFILE\.openagents\coder"`). Chats you synced to your account stay there until you delete them on [openagents.com](/). ## Windows Coder, its chats, and the `openagents` command work on Windows. Local task services and background automation need macOS or Linux for now. ## Web and phone Nothing to install for the web: chat at [openagents.com](/) in any browser. The iPhone app is in beta; see [OpenAgents for iPhone](/docs/iphone). Next: [Chat on openagents.com](/docs/website). --- Source: https://openagents.com/docs/website # Chat on openagents.com The [homepage](/) has a message box. Type what you want to ask and send it. The site opens a new chat at an address under `/chat/`. Enter sends the message. Shift+Enter inserts a line. Without scripts, use **Send**. The [download](/download) link still works either way. ## What it doesn't do The website chat does not start Coder or open a screen. It does show Coder's chats from a computer you [connected to your account](/docs/connect-a-computer), and a reply there reaches Coder while it's open on that computer. For more, use [OpenAgents for Mac](/docs/mac), [OpenAgents Terminal](/docs/terminal), or [OpenAgents for iPhone](/docs/iphone). Next: [OpenAgents for Mac](/docs/mac). --- Source: https://openagents.com/docs/mac # OpenAgents for Mac OpenAgents for Mac is where you chat with OpenAgents on your computer, run Coder in your projects, and connect your phone to the Mac. It isn't published for download yet; build it from [source](https://github.com/OpenAgentsInc/openagents). To use Coder on a Mac without it, run the one-line install on the [download page](/download). ## The window - **The sidebar** lists your chats: pinned first, then recent, then archived. Drag its edge to resize it. **Cmd+B** hides or shows it. - **New chat** (Cmd+N) starts a chat at the top of the list. - **The composer** at the bottom is where you type; the Enter key sends. - **The footer** opens the **Map**, the **Verse**, **Phones and computers**, and **Settings**. You can search, pin, rename, and archive chats, and a reply can be stopped and retried. Chats are text only for now: there is no attach button, and a pasted image is dropped. ## Keyboard shortcuts | Keys | Does | | --- | --- | | Cmd+N | New chat | | Cmd+F | Search chats | | Cmd+K | Commands | | Cmd+, | Settings | | Cmd+. | Stop receiving the reply | | Shift+F10 | Chat actions | | Cmd+B | Show or hide the sidebar | **Settings → Keyboard shortcuts** lists them. They can't be changed yet. ## Coder on this Mac When you ask for coding work in a chat, Coder starts right here, in your project, with the first coding agent that's signed in on this Mac. Its steps stream into the chat, and when it finishes you can open **What changed** to see the diff. See [Coder](/docs/coder). The sidebar shows each coding agent, whether it's signed in, and how much of its usage window you've used; **Settings → Coder** shows the details. **Saved sessions** lists the Codex and Claude Code sessions saved on this Mac. Open one to read it, or choose **Continue with Coder** to hand its newest part to [Coder](/docs/coder) as a new task. ## Your phone **Phones and computers** shows the QR code your phone scans, the phones that can reach this Mac with **Remove** beside each, and Coder's recent work. See [Connect a computer](/docs/connect-a-computer). ## More pages - **The Map** shows how OpenAgents routes a message: the router, its routes, the answers and knowledge behind them, Coder, the coding agents, and the plugins. See [Decks and the Map](/docs/decks). - **The Verse** shows the Grid, a shared world, live. Choose **Play** to walk around in it. See [The Verse](/docs/verse). - **Decks** open full screen from a chat. See [Decks and the Map](/docs/decks). ## Notifications and updates When Coder asks a question, finishes, or fails while OpenAgents isn't in front, a notification names the chat (never the message). Turn them off in **Settings → Notifications**. When an update is ready, a strip says **Update ready**; click **Restart to update**. ## Linux and Windows OpenAgents for Linux and Windows aren't published for download yet; build them from [source](https://github.com/OpenAgentsInc/openagents). The Verse page isn't available on Windows. Next: [OpenAgents for iPhone](/docs/iphone). --- Source: https://openagents.com/docs/iphone # OpenAgents for iPhone OpenAgents for iPhone lets you chat with OpenAgents anywhere and send coding work to your computers. It's in beta on TestFlight: install [TestFlight](https://apps.apple.com/app/testflight/id899247664) from the App Store, then open [testflight.apple.com/join/dvQdns5B](https://testflight.apple.com/join/dvQdns5B) on your iPhone to install the app. The app has four tabs along the bottom. ## Chat The Chat tab opens on a menu: your trainer name and level, a **Next:** line, **Chat with OpenAgents**, and starter questions such as **Test a plugin**, **What's new**, and **Check a result**. - **Chat with OpenAgents** opens a new chat, ready to type. You don't need a computer or an account. - **Earlier chats** are behind the menu button at the top left, newest first. A [connected computer](/docs/connect-a-computer)'s own chats (the ones started in the Mac app or the Terminal) are listed there too, labelled with the computer. Open one and send a message, and the computer answers it. - **Under a reply** you may see buttons: **Run Coder on** a computer, **Connect a computer**, a screen to open, or a command card with **Run**. Nothing happens until you tap one. - **The keyboard** goes away when you tap outside it. When a message is coding work and your computer is set to start Coder at once, Coder starts there without a tap, and the chat shows where it runs with **Stop**. See [Coder](/docs/coder). Chats are text only: there's no attach button. Voice dictation, a model picker, and push notifications when a task finishes aren't built yet. ## Verse The globe tab puts you in the Grid, a shared world where other players walk around live. See [The Verse](/docs/verse). ## Wallet A bitcoin wallet on mainnet, with its keys on your phone. See [Wallet](/docs/wallet). ## Account - **Computers:** your computers, each with a one-word status, and **Connect a computer**. See [Manage computers](/docs/manage-computers). - **Tailnet:** an optional Tailscale sign-in that lists your tailnet's devices. - **Identity keys:** this phone's public key, and its secret key behind **Reveal nsec**. - **Trainer:** your trainer card, level, and XP. See [The Gym and XP](/docs/gym-and-xp). - **Playtest**, **Report a problem**, and **My reports**. - **About this device** (the app's version and build) and **Changelog** (what each build brought). Long-press the tab bar on any screen to report a problem from where you are. ## Android The Android app has the same four tabs and runs the same code underneath. It is still in testing and isn't published; build it from [source](https://github.com/OpenAgentsInc/openagents). Next: [OpenAgents Terminal](/docs/terminal). --- Source: https://openagents.com/docs/terminal # OpenAgents Terminal OpenAgents Terminal is a full-screen chat with OpenAgents in your terminal. When a message is coding work, Coder runs on this computer, in the folder you started from, and its steps stream into the same screen. It works over SSH and in tmux. To install it on macOS or Linux, run `curl -fsSL https://openagents.com/cli/install.sh | bash`; for Windows, see [Download](/docs/download). ## Start it ```sh openagents # or: openagents terminal openagents terminal --continue # the last thread you had open in this folder openagents terminal --thread ID # a thread by its ID openagents terminal --scratch # a throwaway identity, for trying it out ``` It opens on a new thread. When you quit, it prints the thread's ID and the command that reopens it. ## The screen The welcome card shows three rows: - **Project:** the Git checkout you started in, where Coder would work. - **Agents:** the coding agents ready on this computer, such as Codex, Claude Code, and Grok Build. - **Chats:** `synced` when this computer's host is running (the Mac app runs it), so your threads are the Mac app's threads and a connected phone sees them; `this computer` when no host runs; `scratch` for `--scratch`. The line above the composer says what's happening (`ready`, `replying`, `Starting Grok Build…`, `Coder · step 4 · ≈40% done · 12s`). The line under it names the coding agent and the thread. ## Keys | Key | Does | | --- | --- | | Enter | Send. On an empty line, start the Coder run OpenAgents offered. | | Option+Enter (Alt+Enter on Linux), Ctrl+J | A new line. | | Esc | Stop the reply or the Coder run. Closes a list. | | Ctrl+T | The thread list. | | Ctrl+O | Show every step of Coder's runs in full, or fold them again. | | Ctrl+S | Keep this computer's chats in sync with your phone. | | PageUp, PageDown | Scroll. | | Up, Down | Move in the message, then through your earlier messages. | | Ctrl+C | Clear the message; on an empty line, press it twice to quit. | | Ctrl+D | Quit, on an empty line. | The usual line-editing keys work too: Ctrl+A, Ctrl+E, Ctrl+W, Ctrl+K, Ctrl+U, Alt+B, and Alt+F. ## Slash commands A message that is exactly one of these is a command. Anything else goes to OpenAgents. | Command | Does | | --- | --- | | `/new` | Start a new thread. | | `/threads` | List threads to open, start, or archive (also Ctrl+T). | | `/stop` | Stop the reply or the Coder run (also Esc). | | `/export` | Save this thread as a trajectory file. | | `/settings` | Show Coder's settings and where the file is. | | `/connect` | Show a QR code to connect a phone. | | `/plugins` | List published plugins. | | `/expand` | Show or fold every step (also Ctrl+O). | | `/help` | Show these commands and keys. | | `/quit` | Close the screen. A Coder run keeps going. | ## Coder runs When a message is coding work, Coder starts at once (unless your settings say to ask first; then press Enter on an empty line). It works in its own copy of your checkout, so your files aren't touched. See [Worktrees and changes](/docs/worktrees-and-changes). - Reads and searches fold into one line (`Read 3 files, Searched 2 patterns`); each command or edit is its own line with its exit code. - **Esc stops the run.** - **Quitting leaves it running.** Reopen the thread and the screen follows it again from the start. - **When Coder asks a question**, type your answer. - **A follow-up after a run** continues the same work. - **"Work on #123"** works a GitHub issue. Keep the screen open until it lands. See [Work on a GitHub issue](/docs/github-issues). ## Threads Ctrl+T lists threads: pinned first, then newest, then archived, as in the Mac app and on the phone. Enter opens one, `n` starts a new one, `a` archives the selected one, and Esc closes the list. ## Sync and pairing With no host running, the welcome card offers **Ctrl+S**: it installs this computer's host as a background service, so your threads sync with a connected phone. If something is missing, it tells you the one thing to do instead, usually opening the Mac app. It never installs anything you didn't ask for. `/connect` draws a QR code in text, so it works over SSH. Scan it with the OpenAgents app on your phone (**Account → Computers → Connect a computer**). ## Where it keeps things - Threads: in the host's store, or in `~/.openagents/chat/` without a host. - Exports: `exports/` in that folder. - Coder's tasks: `~/.openagents/tasks`. It draws in white on near-black. Set `NO_COLOR` for no color at all. Next: [The openagents command](/docs/cli). --- Source: https://openagents.com/docs/cli # The openagents command `openagents` is the command-line program that comes with Coder. Use it to run Coder from a script, chat from a script, change settings, work with plugins, and connect phones to a computer without a screen. It installs with Coder; see [Download and install](/docs/download). Every command takes `--json` for machine-readable output and `--help` for its syntax. `openagents doctor` shows which identities, stores, and relays it uses. ## Chat ```sh openagents chat "How do I connect a phone?" # a new thread openagents chat --thread ID "And on Android?" # continue a thread echo "What is the Gym?" | openagents chat - # the message from stdin openagents chat threads # your threads, newest first openagents chat read --thread ID # a whole thread openagents chat export --thread ID # a thread as a trajectory file openagents chat send "Plan the budget" --project finances # a new chat in a project ``` `--project` starts the chat inside one of your projects on openagents.com (by its name, repository, or id), as starting a chat in that project on the website does. OpenAgents answers it there, the reply streams here, and the chat shows in the project on the website and the phone, and in `openagents projects threads finances`. The reply streams to standard output, and everything else (the thread ID, offers, suggestions) goes to standard error, so `reply=$(openagents chat "…")` captures only the reply. When a message is coding work, Coder runs on this computer at once, in the Git checkout you run the command in, and its steps stream to the terminal. ```sh openagents chat send --no-run "add a test for slugify" # only offer Coder openagents chat run-coder --thread ID # accept the offer later openagents chat follow --thread ID # watch a run openagents chat answer --thread ID "yes, use the smaller fix" openagents chat stop --thread ID openagents chat work --issues 101,102 # work GitHub issues ``` Ctrl-C stops following a run; the run keeps going. See [Coder](/docs/coder) and [Work on a GitHub issue](/docs/github-issues). When the Mac app (or another host) runs on this computer, these are the same threads it shows. Without one, the command keeps its threads in `~/.openagents/chat/`, and they move into the host's store the first time a host runs. `--scratch` uses a throwaway identity and thread. ## Coder `openagents coder` runs Coder's chat without the screen, and manages its models, plugins, agents, and saved chats: ```sh openagents coder chat -p "Explain this folder." --session first # a chat openagents coder delegate --to codex --task "Review the last commit" openagents coder models list openagents coder plugins list openagents coder sessions list ``` See [Coder from scripts](/docs/coder-scripts). ## Settings ```sh openagents settings show openagents settings set coder.start ask_first openagents settings unset coder.start ``` Every key is in the [settings reference](/docs/settings). ## Projects and GitHub boards Your projects on openagents.com (the Projects list on the website) are `openagents projects`. GitHub Project boards are a different thing, under `openagents board`: ```sh openagents projects list # your openagents.com projects openagents projects show finances # one project and its chats openagents projects files list finances # its files and notes openagents board list --project 22 --status Todo # a GitHub board's items openagents board move 101 --status "In Progress" # move an issue on its boards ``` Coder runs the `openagents` installed beside it, so its commands always match the Coder you run. ## Plugins ```sh openagents plugin list # published plugins openagents plugin run DIR --in PROJECT --request "..." openagents plugin test init # write tests with us openagents plugin test run . # test with and without openagents plugin test publish REPORT # add a result to the Gym openagents plugin test check RESULT_ID # rerun someone's result openagents plugin defaults sync # the plugins Coder uses for everyone ``` See [Plugins](/docs/plugins) and the guides after it. ## Models Call any model on the [OpenAgents API](/docs/api) with your key in `OPENAGENTS_API_KEY`: ```sh openagents inference google/gemini-3.8-flash "Say hello." openagents inference openagents/chat --input "Tell me a story." --stream openagents inference openagents/fast --json '{"input": "Hi", "temperature": 0.2}' openagents inference models # every model and its price openagents inference rates # the rate card ``` `--format json` prints the whole answer and `--format events` each streamed event. With no key, `--pay x402 --max-msat N` pays for one request from your wallet ([Pay per request](/docs/api/pay-per-request)). ## Connect For a computer without the Mac app, or to script pairing. The host must be running. ```sh openagents connect invite # a QR code for the phone, in the terminal openagents connect devices # the phones that can reach this computer openagents connect remove DEVICE # cut a phone off now openagents connect status # this computer's host at a glance openagents connect --ssh me@box # set up a computer you reach over SSH ``` `connect --ssh` installs `openagents` on the other computer, starts its host, and pairs it with this one. Set up SSH key login first. On Windows, `connect` and a few other commands say they need macOS or Linux. ## More The command also covers the Verse, XP, keys, relays, a Lightning wallet for agents, and more. `openagents --help` lists every group, and the full reference is on [GitHub](https://github.com/OpenAgentsInc/openagents/blob/main/docs/cli/README.md). `openagents mcp serve` offers the command to other agents over MCP. Next: [Chat](/docs/chat). --- Source: https://openagents.com/docs/chat # Chat Chat is where you talk with OpenAgents. It's the same chat on the website, the Mac app, the iPhone app, and the Terminal. OpenAgents answers as "we". ## What you can ask - **About OpenAgents.** How to connect a phone, what a plugin is, what's new in the Gym, how the wallet works. These are answered from our product notes. - **About your work.** Plan a change, ask how something works, or ask what Coder just did. - **Anything else.** A general question gets a general answer. - **Coding work.** "Fix the failing test", "add a unit test for slugify", "work on #123". These go to Coder on your computer, as described below. - **To open something.** "Open my wallet", "show me how you route things", "show the test-time capabilities deck" open that screen in the app that has it. To start fresh, choose **New chat** (Cmd+N on the Mac, `/new` in the Terminal). Every chat goes to OpenAgents; there's nothing to pick. ## Why some answers appear at once A small, fast model, Jev from TypeSafe, reads each message first and decides how we reply. When one of our prepared answers, or an entry in our product notes, fully answers the question, it shows in about half a second. Otherwise a larger model writes the reply, which takes a few seconds. A prepared answer often has follow-up questions under it to tap. ## When Coder starts When a message is coding work, the reply says so and Coder starts on a computer: - **On a computer** (the Mac app, the Terminal, `openagents chat`), Coder starts right there at once, in your project. If you set Coder to **ask first**, the reply offers **Run Coder** instead. - **On the phone**, Coder starts on your connected computer at once if that computer allows it; otherwise the reply shows **Run Coder on** your computer. Without a computer, it offers **Connect a computer**. A reply that already answered your question never starts Coder. See [Coder](/docs/coder). ## Use it as much as you like We don't count your messages per minute or per day. If you ever see "Couldn't reach OpenAgents; try again.", send the message again. A very long conversation may ask you to start a new chat. ## What the chat can't do From the chat itself we can't read your files, run code, or reach your computer. That's Coder's job, and it happens only on a computer you connected or are using. Next: [Privacy and security](/docs/privacy-and-security). --- Source: https://openagents.com/docs/privacy-and-security # Privacy and security ## Your chats - **No account needed.** The apps have no account or password. Your phone or computer makes its own key the first time it runs and signs every message with it. On the website, the site signs your messages for you. - **In the web chat** on openagents.com, we save your chats on our servers. Our team can read them. - **Signed in** (with GitHub), your chats belong to your account: you see them in any browser where you sign in, and after you sign out, someone else using that browser doesn't. Chats you started in that browser before signing in move to your account when you sign in. - **Not signed in,** a random cookie tells this browser's chats apart. Only this browser opens them, and anyone using it can. If you clear your cookies, you can't open them again. - **Deleting.** To delete a chat, open it and choose **Delete chat**. To delete every chat, choose **Delete all chats**: in Settings when signed in, or on a chat's delete step when not. Chats are removed from our servers right away, though our storage provider may keep a copy we can recover for up to 7 days. Chats you don't delete stay; there's no time limit yet. - **Exporting.** Signed in, open [Settings](https://openagents.com/settings) and choose **Download** under **Your data** (or go straight to [openagents.com/settings/export](https://openagents.com/settings/export)). You get one file with every chat (each with a Markdown copy to read), your projects, your uploaded traces, your signed-in computers, and your settings. It opens in any text editor, without OpenAgents. It holds only your own account's things, and never a key, token, or password: an API key shows by name only, and a saved Claude credential by its kind only. From a terminal signed in with `coder login`, `coder export --account` saves the same file (`--output FILE` to choose where). - **In the Mac app, Terminal, and phone app,** your chats are saved on your device, encrypted with its key (on a computer, by its host). Your messages are encrypted before they leave your device, and the OpenAgents relay that carries them to our chat service sees only the encrypted form and keeps nothing. When your phone reaches your computer through the relay, the relay holds those messages, encrypted, for that phone and computer only. - **Our chat service doesn't keep your message text.** It records each request's time, key, surface, route, model, token counts, and timings for usage statistics, and deletes those records after 30 days. - **Training.** We may use your chats to train and improve our models. On a paid plan you can ask us to opt you out; we set that up with you. - **Reports.** If you send a problem report and choose to share the chat, that chat goes to our team with it. ## Who sees what To answer, our chat service sends your messages to these services: - **Google's Gemini 3.8 Flash**, on Google's Vertex AI, through OpenRouter, or through the Vercel AI Gateway (and Gemini 2.5 Flash, through the same gateway, for some Gym news replies). - **GLM**, through OpenRouter or the Vercel AI Gateway, as a backup when Gemini doesn't answer. - **TypeSafe's Jev**, which decides how we reply. Jev is reached through the Vercel AI Gateway first, then OpenRouter, then TypeSafe directly. - **OpenRouter**, for a short personalized line in some replies that hand work to Coder. - **OpenAI embeddings, through the Vercel AI Gateway**, when a question is answered from our product notes, our code, or the Gym's records. When we send your messages to Gemini, GLM, or the OpenRouter model that writes personalized lines, we ask the model provider not to keep them or train on them. If a model's provider can't agree, we don't use that model. We don't ask this of Jev or the embeddings yet. When you chat on a computer, or from a phone connected to one, each message also names that computer and the chat's project folder; after Coder runs in a chat, the next messages carry what it reported, the files it changed, and its commands. Only our chat service and the chat model read those. Ask the chat "What happens to my messages?" and it answers with the services it uses right now. ## What we count on the website We count how openagents.com is used ourselves. There's no outside analytics service, no tracking script from another company, and no cookie for it. - **What we count:** which page was opened (the kind of page, not its full address: every chat counts as "a chat"), the name of the site that sent you (like `ycombinator.com`), whether you're on a phone, tablet, or computer, whether the visit came from a person, an AI agent, or a crawler, how fast the page loaded, and a few actions: sending a chat, getting an answer, clicking a suggestion or a card, clicking a download, copying the install command, and signing in. - **What we don't:** your IP address, cookies, your account, what you write, or anything that tells one visitor from another. We keep hourly totals, so we can't tell whether two visits came from one person. - **Do Not Track and Global Privacy Control:** with either one on in your browser, we count only that the page was opened, and nothing else. - **How long:** the hourly totals are kept for 13 months. Our hosting provider's request logs, which keep the site running and secure, do see IP addresses; they're deleted after 30 days. ## Your computer - A phone can reach your computer only after you scanned that computer's QR code (or pasted its code, or approved it on the computer's screen). - Every connected phone gets full access to that computer, a terminal included. The computer checks each message against that access. **Remove** in the Mac app cuts a phone off at once. - The Mac app keeps its keys in the Mac's keychain. - Coder works on your computer, in your projects. Like Codex or Claude Code on their own, the coding agent it runs sends what it reads to that agent's model provider, under your sign-in there. - By default Coder approves its own steps, including a push, so it can finish without stopping to ask. To run it inside a stricter boundary, see `coder.access` in the [settings reference](/docs/settings). In the `coder` terminal app, production deploys, merges, secrets, payments, and DNS changes always wait for you; see [Safety](/docs/coder-safety). ## Your phone's keys - **Device key:** made on your phone, kept in its Keychain on this device only, and never synced. It holds access to your computers. - **World key:** a separate key for the Verse and your XP, so other players can't link you to your device key. - **Wallet:** its own recovery words, separate from both. The full details are in the [Privacy Policy](/privacy) and the [Terms of Service](/terms). Next: [Coder](/docs/coder). --- Source: https://openagents.com/docs/coder # Coder quick start Coder is a coding agent in your terminal. Run `coder` in a project folder and ask in plain words: explain this code, fix that test, add a feature. It reads, edits, and runs commands in that folder, and shows each step as it goes. Coder works with the coding agents you already have. It can answer through Claude Code, Codex, or OpenCode on your own sign-in, hand work to other agents on your computer, or use its own coding loop on OpenAgents models. You don't need an API key to start. ## 1. Install On macOS or Linux: ```sh curl -fsSL https://openagents.com/cli/install.sh | bash ``` On Windows, in PowerShell: ```powershell irm https://openagents.com/cli/install.ps1 | iex ``` Open a new terminal and check the version: ```sh coder --version ``` Updates install themselves. See [Download and install](/docs/download) for what gets installed, updating, and uninstalling. ## 2. Sign in ```sh coder login ``` Coder opens [openagents.com/device](https://openagents.com/device) in your browser, or prints that address and a code when it can't (over SSH, for example). Check that the page shows the same code as your terminal, then approve. Coder then asks once where this computer's chats should live: 1. **Sync all my chats:** they show on openagents.com and in the phone app, earlier ones too. 2. **Keep chats on this computer:** nothing is sent. Type `1` or `2`, or answer on the website. You can change it later with `/sync`; see [Sync, share, and export](/docs/coder-sync). Signing in is optional. Without it, Coder answers through Claude Code, Codex, or OpenCode if one of them is set up on this computer. Signed in, it can also use OpenAgents models, with a free daily allowance (see [Pricing](/docs/pricing)). ## 3. Open a project ```sh cd my-project coder ``` You see the input at the bottom, with **Auto** at its top right (who answers) and your folder and Git branch at its bottom right. Type a message and press `Enter` to send. `/` lists every command. ## 4. Ask for something Try a question first: ```text What does this project do? Name the three files I should read first. ``` Then a small change: ```text Add a short "Getting started" section to the README. Show me the diff. ``` Each step shows as a line: files read, searches, edits with their diff, and commands with their output. Press `Ctrl+O` to show each step in full. Press `Esc` to stop a reply. If you don't like a change, type `/rewind` (in the next release), pick the message, and Coder puts the files back as they were before it. ## 5. Keep going - `Ctrl+N` starts a new chat; `/resume` opens an earlier one. - `Shift+Tab` chooses who answers: Auto, Claude Code, Codex, OpenCode, or another agent on this computer. - `/models` picks the model; `/plugins` (or `Ctrl+P`) turns plugins on and off. - `Ctrl+C` quits. Your chat is saved. ## The Coder guides | Guide | What it covers | | --- | --- | | [How Coder works](/docs/coder-how-it-works) | Quick decisions in front of the big model, one chat in front of every agent, and the steps that wait for you. | | [Use Coder in the terminal](/docs/coder-terminal) | The screen, keys, commands, chats, memory, and attachments. | | [Choose who answers](/docs/coder-agents) | Auto, `Shift+Tab`, models, preferences, handing work to other agents, and background agents. | | [Coder's plugins](/docs/coder-plugins) | What each built-in plugin does, and how to set up keys. | | [Solve an issue](/docs/coder-solver) | From a GitHub issue to a pull request. | | [Safety](/docs/coder-safety) | What Coder asks you before doing, and how it protects your work. | | [Sync, share, and export](/docs/coder-sync) | Your chats on openagents.com and your phone, and saving them to files. | | [Coder from scripts](/docs/coder-scripts) | `openagents coder` for scripts and other agents. | Found a problem? [Report it on GitHub](https://github.com/OpenAgentsInc/openagents/issues) with your system, Coder's version (from the version command above), and what you saw. Leave out keys and private code. Next: [How Coder works](/docs/coder-how-it-works). --- Source: https://openagents.com/docs/coder-how-it-works # How Coder works Coder sits between you and the coding agents you already use. It makes the quick calls itself, sends only the hard part of the work to the big model, and holds the few steps that are hard to undo until you say yes. This page shows how, with the numbers from our own test. ## Most agents send every step to the big model ![Another harness: three messages run straight into a large glowing circle, the big model. A thin ring around it holds only its own commands: Bash, Read, Edit, Write, Grep, and Web. Every result goes back into the model. Plain Claude Code in our test: $4.00 per accepted fix, 284 seconds median.](/static/docs/coder-harness.svg) In most coding agents, your message goes straight to one big model, and so does every step after it. Reading a file, searching, running the tests: each result goes back into the model, and the model reads the whole conversation again before the next step, so a long test log is read again on every step after it. That is where the time and the money go. The numbers in the picture are plain Claude Code's, from the test below. ## System 1 in front ![Coder: the same messages stop at a ring of quick decisions (route, brief, trim, gate, notes, check) around a smaller big model. Two take a short hop to nearby answers, your code and the commands; only the fix goes on to the model. $1.84 per accepted fix instead of $4.00, 121 seconds median instead of 284.](/static/docs/coder-system-1.svg) In our test, the same model (Claude Opus 5.5) fixed 21 closed issues three times each: once as plain Claude Code, and once with a briefing in front and only the commands it needed. Both got 19 of 63 fixes accepted. With the briefing, each accepted fix cost $1.84 instead of $4.00, and the median run took 121 seconds instead of 284. [How we measured it](https://github.com/OpenAgentsInc/openagents/blob/main/docs/inference/briefed-agent-ab.md). Coder puts a ring of quick decisions in front of the big model. We call it System 1: small judgments made in a fraction of a second, before the big model sees anything. The big model is System 2, kept for the part that needs it, which is writing the change. - **Route.** Each new message goes where it's best answered. A question Coder can answer from what it knows doesn't wake the big model, and unrelated new work starts fresh instead of dragging the old conversation along. - **Brief.** Coder finds the files that matter and hands them over, so the agent doesn't spend its first minutes searching. - **Trim.** Long build and test output reaches the agent as the lines that decide the next step. The whole output is saved to a file it can open. - **Gate.** A script the agent hasn't read waits for a read first when running it blind looks risky. - **Notes.** The first time the agent works in a folder, it gets that folder's own instructions. - **Check.** An agent working on an issue that says it's done without passing its checks is sent back with what failed. These come together as the **Token savers** plugin, on by default. You can turn it off in `/plugins`; see [Coder's plugins](/docs/coder-plugins). ## One Coder in front of every agent ![One Coder in front of every agent: Coder at the center, in a ring marked Auto, with Claude Code, Codex, OpenCode, Grok Build, Devin CLI, and Cursor around it. A light steps from agent to agent, as Shift+Tab does.](/static/docs/coder-agents.svg) Coder isn't another agent to switch to. It's the same chat in front of the agents you already have: Claude Code and Codex on your own plans, OpenCode, Coder's own loop, and others such as Grok Build, Devin CLI, and Cursor when they're installed here. A new chat starts on **Auto**, and Coder picks who answers. Press `Shift+Tab` to choose yourself: Auto, then Claude Code, Codex, OpenCode, and the other agents found on this computer. Any chat can also hand a piece of work to another agent and keep going. See [Choose who answers](/docs/coder-agents). ## Hard-to-undo steps wait for you ![Hard-to-undo steps wait for you: from Coder, reading, editing, running tests, and pushing go straight through. A deploy, a merge, a secret, a payment (in gold), and a DNS change each stop at a hold until you press Y to allow or N to deny.](/static/docs/coder-holds.svg) Ordinary work goes ahead without asking: reading and editing files, builds, tests, and pushing commits. Five kinds of step always wait for you, whichever agent is answering: a production deploy, merging a pull request, reading or changing a secret, a payment, and a DNS change. Coder shows the exact command and asks one plain question. `Y` allows it this once; `N` or `Esc` denies it, and the agent carries on with the rest of the work. See [Safety](/docs/coder-safety). Next: [Use Coder in the terminal](/docs/coder-terminal). --- Source: https://openagents.com/docs/coder-terminal # Use Coder in the terminal Run `coder` in a project folder to open it there. To open it on another folder from where you are: ```sh coder --in ~/code/my-project ``` It works in any terminal, over SSH, and in tmux. Install it from [Download and install](/docs/download). ## The screen - **The chat** fills the screen: your messages, Coder's replies, and each step it takes (files read, searches, edits with a diff, and commands with their output). - **The input** sits at the bottom, between two lines, starting with `❯`. - **Top right of the input:** who answers this chat (`Auto`, or the agent you picked) and, once it has answered, the model, such as `Auto → Claude (Haiku 5.5)` ("Auto picked Claude"; the chat can still move). An agent you picked shows alone, such as `Claude (Haiku 5.5)`. Whenever a turn uses your Claude or Codex plan, on any agent, it also shows how much of that plan's usage windows you've used, such as `5h 12% · week 15%`, or `Auto → Coder (Haiku 5.5) · Claude 5h 12% · week 15%` when Coder's own loop ran on your Claude plan. Otherwise Coder's own loop shows the chat's cost so far. Once the model has answered, it shows how much of the model's room for this chat is used. See [Choose who answers](/docs/coder-agents). - **Bottom right of the input:** the folder Coder works in and its Git branch. - **Under the input:** once this chat has handed work to an agent, a list of chats: `main` (this one) first, then one row for each agent with what it is doing right now, and its time and tokens on the right. The chat you are looking at has a `❯` and a filled dot `●`; the others have an empty dot `○`. A line above names the keys (`↑/↓ to select · esc for main`), and `↓ 3 more` says when the list is longer than the room. See [Choose who answers](/docs/coder-agents). ## Keys | Key | Does | | --- | --- | | Enter | Send. | | Shift+Enter, Alt+Enter | A new line. | | Esc | Stop the reply. Closes a list or screen. Twice on a draft clears it. | | Shift+Tab | In a new chat, before its first message: choose who answers (Auto, Claude Code, Codex, OpenCode, or another agent here). | | Tab | Complete a `/` command. | | Up, Down | Your earlier messages; Down from the input selects the agent rows under it. | | Ctrl+N | Start a new chat in the same folder. The last one stays in `/resume`. | | Ctrl+O | Show each step in full, or fold the steps back to one line each. | | Ctrl+P (Cmd+P on macOS), F2 | Open plugins. | | PageUp, PageDown, mouse wheel | Scroll the chat. Ctrl+End jumps to the bottom. | | Ctrl+A, Ctrl+E | Start or end of the line. | | Cmd+A | Select the whole input, where the terminal passes Cmd keys on. Terminal, iTerm2, and Ghostty keep Cmd+A for themselves: use Ctrl+Shift+A there. | | Drag | Copy text from the chat. Double-click copies a word, triple-click a line. | | Click a message | Shows the model that wrote it (or answered it), such as `Codex · GPT-6.1-Sol`, at the right of that line for about three seconds. | | Ctrl+C | Quit. The chat is saved. | ## Commands Type `/` to see them above the input; keep typing to filter, and press `Enter` to run one. | Command | Does | | --- | --- | | `/help` | Every command and key. | | `/models` | Choose the model of whoever answers, before the chat's first message. | | `/plugins` | Turn plugins on and off, and add keys. See [Coder's plugins](/docs/coder-plugins). | | `/preferences` | How much to favor cost, speed, or intelligence, and your saved choices of agent. | | `/resume` | Open an earlier chat. `/resume 3` picks from the last list; `/resume ID` opens one by its ID. | | `/rewind` | Undo a turn's file changes and go back to its message. | | `/export` | Save this chat to a file. `/export PATH` chooses where. | | `/compact` | Summarize the older part of the chat so the model reads less. | | `/memory` | What Coder remembers. `/memory forget NAME` deletes one note. | | `/agents` | Background agents: open, stop, message, or resume one. | | `/agent` | Start a background agent: `/agent codex fix the flaky login test`. | | `/loop` | Repeat a prompt while Coder is open: `/loop 5m check the deploy`. `/loop stop 1` or `/loop stop all` ends them. | | `/schedule` | Run a prompt on this computer on a schedule, even while Coder is closed: `/schedule weekdays 09:00 triage new issues`. `/schedule remove ID` deletes one. | | `/shells` | Commands running in the background. `/shells stop ID` stops one. | | `/login`, `/logout` | Sign in to openagents.com, or sign out. | | `/sync` | Save chats to your account: `/sync on`, `/sync off`, or `/sync delete`. See [Sync, share, and export](/docs/coder-sync). | | `/appearance` | Use your terminal's own background color instead of Coder's. | | `/brainstorm` | Public profile lookups, when the Brainstorm plugin is on. | ## Chats Every chat saves itself as you go, on this computer, in `~/.openagents/coder/sessions/`. - **New chat:** `Ctrl+N`. It starts in place, in the same folder. - **Earlier chats:** `/resume` lists your 100 most recent. Up and Down (or `j` and `k`) choose, `Enter` opens, `Esc` goes back. A resumed chat comes back with everything it showed, without running anything again. - **Undo a turn:** `/rewind` lists your last 20 messages, each with the files its turn changed. Pick one: Coder puts back the files that turn and every later turn changed (and deletes files they created), cuts the chat to just before that message, and puts the message back in the input for you to edit and send again. A file someone changed outside Coder since then is left as it is and named. Files over 1 MB and binary files can't be put back; the list says so. - **Stop:** `Esc` stops the reply. What was done so far stays. Stop a running reply before you resume or rewind. ## Send more than text - **Screenshots and files:** paste a screenshot, drop or paste the path of an image or a PDF, or write `@path/to/file` in your message. Up to 8 per message; an image up to 5 MB, a PDF up to 20 MB. - **A shell command:** type `!` on an empty input, then the command, such as `!git status`. It runs in your folder and its output joins the chat. `Backspace` on the empty input goes back to a normal message. - **While Coder works:** on Coder's own loop, a message you send waits and goes next. ## Instructions and memory Every turn, Coder reads your project's `AGENTS.md` and `CLAUDE.md` files, from your folder up to your home folder, plus your own `~/.openagents/AGENTS.md`. Coder also keeps short notes across chats: about you (for every project) and about this project. Say "remember that we use pnpm" to add one and "forget the pnpm note" to remove it. `/memory` lists them. Notes stay on this computer, under `~/.openagents/memory`, and anything that looks like a password or key is refused. Set `OPENAGENTS_MEMORY=off` to turn instructions and memory off. ## Where Coder keeps things | What | Where | | --- | --- | | Chats | `~/.openagents/coder/sessions/` | | Settings, plugins, and keys | `~/.openagents/coder/` (only you can read the files) | | Exports | `~/.openagents/exports/` unless you name a path | | Memory | `~/.openagents/memory/` | To keep all of Coder's data in another folder instead: ```sh coder --state ~/coder-data ``` Next: [Choose who answers](/docs/coder-agents). --- Source: https://openagents.com/docs/coder-agents # Choose who answers Coder is one chat, whoever answers it. Each chat runs on one of these: | Who | What it needs on this computer | | --- | --- | | **Claude Code** | Claude Code installed and signed in to your Claude account (`claude`, then sign in). | | **Codex** | Codex installed and signed in with ChatGPT (`codex`, then sign in). | | **OpenCode** | OpenCode installed ([opencode.ai](https://opencode.ai)). It can use its free model or the models you set up in it. | | **Coder's own loop** | Your openagents.com sign-in (`coder login`), or an OpenRouter key. | | **Other agents** | Devin CLI, Cursor, Grok Build, Amp, Goose, and others, each installed and signed in with its own program. | Claude Code and Codex run on your own plans, so they cost you nothing through OpenAgents. ## Auto A new chat starts on **Auto**, shown at the input's top right. Coder looks at your message and picks who answers among the ones that are on and signed in here. With no other reason to choose, it tries Claude Code, then OpenCode, then its own loop. Once it has answered, the whole chat stays with that agent and model; a new chat (`Ctrl+N`) can pick again. Once Auto has picked, the label says so, with the model once it is known: `Auto → Claude (Haiku 5.5)` or `Auto → Coder (Haiku 5.5)`. An agent you pinned with Shift+Tab shows alone, without Auto: `Claude (Haiku 5.5)`. A short question Auto sends to Coder's own loop runs on a cheap model: OpenAgents' quick model on your free daily allowance when you're signed in (`coder login`), else the cheapest model on your login (Haiku on the Claude plan), never Opus or Sonnet unless you chose them. You can also just ask in your message: "use Codex for this". ## Pick with Shift+Tab `Shift+Tab` steps through who can answer here, in this order: **Auto → Claude Code → Codex → OpenCode → the other agents found on this computer** (such as Devin CLI, Cursor, or Grok Build), then back to Auto. `Shift+Tab` works in a new chat, before you send its first message. Only the ones that can run here are offered, and your draft stays as it is. Once the chat has a reply, it keeps its agent: `Shift+Tab` says "Start a new chat (Ctrl+N) to switch agents" instead. An agent that doesn't ask before every step, such as Cursor, says so once on the line under the input when you pick it. ## Plan windows Beside **Claude Code** and **Codex**, the label shows how much of your plan's usage windows you've used, such as `5h 12% · week 15%`: 12% of the five-hour window and 15% of the weekly one. Auto skips an agent whose window has run out, and leans away from Claude Code when its five-hour window is nearly used up. ## Pick a model `/models` opens the models of whoever answers this chat. Type to search, use Up and Down to choose, and `Enter` to go on; `Esc` steps back. | Who answers | Models in `/models` | | --- | --- | | Claude Code | Haiku 5.5 (the default), Sonnet 5.5, Opus 5.5, and Fable 5.1, each with a reasoning level from low to max. | | Codex | GPT-6.1-Sol (the default), GPT-6-Astra, GPT-6-Sol, and GPT-6-Luna, each with a reasoning level. | | OpenCode | OpenCode's own model list: free models first (newest first, then Big Pickle), then your favorites and recent models from OpenCode, then each provider's models. | | Devin CLI | Devin's own models by family, SWE-2 first. A chat runs SWE-2 Medium unless you pick another. | | Grok Build | The models `grok models` lists, with Grok's default marked. | | Coder's own loop | **Auto** (OpenAgents picks the model), the OpenAgents models your account can use, and, with the OpenRouter plugin on, OpenRouter models on your key. | | Auto, before it has answered | Coder's own loop's models: Auto picks the agent for each message, and these are the models it runs on Coder's own loop. | `/models` always lists the models of the agent shown at the input's top right, including one you just picked with `Shift+Tab`. Pick a model before the chat's first message; the chat then keeps it. After that, `/models` shows the chat's model, and another pick says "Start a new chat (Ctrl+N) to use another model". Each new chat starts on its agent's default model. A chat you reopen with `/resume`, or continue from your phone or the web, goes on with the agent, model, and payment it ran on. If that agent isn't on this computer any more, the line under the input says so and the chat doesn't move to another one. If `/models` says to sign in, run `/login`, or turn on OpenRouter BYOK in `/plugins` ([how](/docs/coder-plugins)). ## Preferences and pins `/preferences` sets how much Auto should favor **Cost efficiency**, **Speed**, and **Intelligence**, each from 1 to 5. Up and Down move, Left and Right (or `-` and `+`) change a value, and each change is saved at once. To make a standing choice, tell Coder in plain words: - "Always use Claude Opus for code in this repo." - "Use Codex less." - "Never use Devin." Coder saves it as a pin, for one project, one kind of work, or everywhere. `/preferences` lists your pins in plain words, and the file it names holds every change with your notes. An agent you said never to use is never started. ## Hand work to another agent Any chat can hand a piece of work to another agent and keep going. Ask for it: "have Codex review this change", "ask Claude Code to write the tests". The agent works in its own conversation, and a row for it appears under the input, below a `main` row for your chat, with what it is doing right now, its time, and its tokens. - `Down` from the input selects the first row, and shows that agent's conversation. - `Up` and `Down` move between agents; `Up` from the first one, or `Esc`, returns to your chat. When it's done, its short report comes back to your chat. From a script or another agent: ```sh openagents coder delegate --to codex --task "Review the last commit for bugs" --read-only ``` `--to` takes `claude-code`, `codex`, `opencode`, `coder`, an agent ID from `openagents coder agents list`, or `auto`. ## Several things at once Send a list of separate jobs and Coder works out which ones need each other. The ones that don't start at the same time, each with its own agent in its own worktree; one that needs another's result waits for it and starts from its changes. Each part gets a row under the input while it works. In a chat you pinned with Shift+Tab, the list still splits, and every part runs on the harness or agent you picked. When they finish, their changes come back to your folder together, the checks they ran are run once on the result, and one report lists how each part went. Coder never overwrites anything: if two parts (or you) changed the same lines, that part's changes stay on its own branch and the report names the branch and the files. Two to four parts run at once, depending on how many cores your computer has. To set your own number, add `"parallel_parts": 2` to `~/.openagents/coder/preferences.json`, or start Coder with it for one session: ```sh CODER_PARALLEL_PARTS=2 openagents coder ``` ## Background agents A background agent works at the same time as your chat, in its own copy of your project (a Git worktree on its own branch), with no time limit. Your chat keeps going, and the agent's report joins the chat when it ends. Start one yourself: ```text /agent codex fix the flaky login test ``` Type `/agent` alone to list the agents you can start here (the ones on in **ACP Subagents**, and `microcoder` for Coder's own loop). The chat can also start them itself when work splits up. `/agents` lists them with their status, time, tokens, and cost: | Key | Does | | --- | --- | | Up, Down | Choose an agent. | | Enter | Open its conversation. | | s | Stop it. | | m | Send it a message. | | r | Resume one that stopped. | | Esc | Close the list. | The agents a chat starts can also talk to each other while they work (the **Agent channel** plugin): each says what it means to change, and they hear when their changes would overlap. Next: [Coder's plugins](/docs/coder-plugins). --- Source: https://openagents.com/docs/coder-plugins # Coder's plugins Coder's abilities come as plugins you can turn on and off. Type `/plugins`, or press `Ctrl+P` (`Cmd+P` on macOS) or `F2`. | Key | Does | | --- | --- | | Up, Down | Choose a plugin. | | Space | Turn it on or off. | | Enter | Open its settings. | | Tab | Move between fields and buttons in settings. | | Esc | Go back. | Your choices are saved and kept when you quit. ## The built-in plugins | Plugin | Starts | What it does | | --- | --- | --- | | **Claude Code** | On | Runs chats on Claude Code with this computer's Claude sign-in: everything Claude Code can do, with your own settings and skills, plus Coder's handoffs to other agents. While it's on and signed in, new chats can run on it. | | **Codex** | On | Runs chats on Codex with this computer's ChatGPT sign-in, with its own models. Auto can pick it, or you can choose it with `Shift+Tab`. | | **OpenCode** | On | Runs chats on OpenCode, with its free model or the models you set up in it; Coder checks each step before it runs. Listed only when OpenCode is installed. | | **Coder loop** | On | Coder's own coding loop, on OpenAgents models with your sign-in or on your OpenRouter key. | | **ACP Subagents** | On | Hands tasks to other coding agents installed here, such as Devin CLI, Cursor, Grok Build, Goose, Amp, or Kimi Code. | | **Solver** | On | Takes a GitHub issue to a pull request. See [Solve an issue](/docs/coder-solver). | | **Solver swarm** | On | Hands several issues to several Solvers at once. | | **Agent channel** | On | Lets the agents a chat hands work to tell each other what they're changing, and warns them about overlaps. | | **Token savers** | On | Cuts what the agent reads and pays for: long build and test output is trimmed to its errors, with the full output saved to a file. | | **OpenAgents CLI** | On | Lets Coder run the `openagents` command in this folder, for example to read and comment on GitHub issues. | | **Jev** | On | Quick judgment calls while Coder works, like whether a step is done, from Jev, TypeSafe's small decision model. Uses your TypeSafe key or a compatible service. | | **OpenRouter BYOK** | Off | Use OpenRouter models with your own OpenRouter key. | | **Brainstorm** | Off | Looks up public profiles and how much influence they have, when you ask with `/brainstorm`. | | **Boat Cloud**, **GCE Cloud** | Off | Run handed-off work on cloud machines you already have access to. | Turning a plugin off keeps its settings and keys, so turning it back on needs no setup. ## OpenRouter BYOK Use any OpenRouter model on your own key ([get one at openrouter.ai](https://openrouter.ai/keys)). 1. In `/plugins`, choose **OpenRouter BYOK** and press `Enter`. 2. Paste your key in **OpenRouter API key**. Press `Tab` to reach **Save**, then `Enter`. Coder checks the key and shows **Verified**. 3. Back in the list, make sure the plugin is on (`Space`). 4. Type `/models` and pick a model. `openrouter/free` is OpenRouter's free router; fixed models also ask for a reasoning level and an output limit. Or start Coder with the key in your environment, and Coder picks it up: ```sh export OPENROUTER_API_KEY=sk-or-... coder ``` Coder also reads `OPENROUTER_API_KEY` from a `.env` file in the folder you open. Keys are never shown on screen; to remove one, clear the field and save. ## Jev Jev answers small typed questions (yes or no, pick one, a score) with probabilities, which Coder and its own loop use for quick decisions. 1. Get a key at [typesafe.ai](https://typesafe.ai). 2. In `/plugins`, choose **Jev** and press `Enter`. 3. Pick the connection (TypeSafe, or Vercel AI Gateway), paste the key, then press `Tab` to reach **Save** and `Enter`. Or set `TYPESAFE_API_KEY` in your environment or `.env` before you run `coder`. ## ACP Subagents Open **ACP Subagents** in `/plugins` to see the coding agents Coder found on this computer, each with a checkbox. New ones start on. - `Space` or `Enter` turns the chosen agent on or off. - `R` looks for installed agents again. Each agent uses its own sign-in. Install and sign in with its own program first: for Cursor, `cursor-agent` with its login or `CURSOR_API_KEY`. Devin CLI bills its own paid service for each run; turn it off here if you don't want Coder to use it. ## Token savers When it's on, long build, test, and lint output (from `cargo test`, `npm test`, `pytest`, `go test`, `make`, and the like) reaches the agent trimmed to the lines that matter, with the whole output saved to a file it can open when it needs more. This works on Claude Code and on Coder's own loop, and Codex is asked to run such commands the same way. Turn it off to send all output through unchanged. ## Plugins you install On macOS and Linux, plugins you install with `openagents plugin install` also appear in the list. `Enter` shows one's details and the commands to turn it on or off. See [Plugins](/docs/plugins) for writing and sharing your own. ## From the command line ```sh openagents coder plugins list openagents coder plugins disable token-savers openagents coder plugins enable openrouter-byok printf '%s' '{"api_key":"sk-or-..."}' | openagents coder plugins configure openrouter-byok --stdin openagents coder plugins check openrouter-byok ``` The plugin IDs are `claude-code`, `codex`, `opencode`, `microcoder` (Coder loop), `acp-subagents`, `solver`, `solver-swarm`, `comms` (Agent channel), `token-savers`, `openagents-cli`, `jev`, `openrouter-byok`, `brainstorm`, `boat-cloud`, and `gce-cloud`. Next: [Solve an issue](/docs/coder-solver). --- Source: https://openagents.com/docs/coder-solver # Solve an issue Solver takes a GitHub issue to a pull request. It works in its own fresh copy of your project, so your checkout isn't touched, and it opens the pull request only when the checks pass. Solver comes in the next Coder release. ## Before you start On the computer that runs it you need: - the project's Git checkout, with `git`; - the GitHub CLI, signed in: `gh auth login`; - Claude Code signed in (the default), or your openagents.com sign-in (`coder login`) so it can run on Coder's own loop. ## From the chat Ask in plain words, naming the issue by its number: ```text Solve #42 ``` A bare number is an issue of the repository your chat's folder is in (its GitHub remote, `origin` first). For an issue in another repository, name it: `Solve acme/web#42`. If the folder has no GitHub remote, Solver asks which repository. Add "without a pull request" to stop after the checks. Solver shows as an agent under the input. `Down` opens its conversation, where each step shows as it happens. When it's done, its report comes back to your chat with the outcome, the pull request, and the cost. Stopping the chat stops the run. ## From the command line Run it in the project's checkout with the issue number: ```sh coder solver 42 ``` It opens a full-screen view of the run. Add `--plain` to print it as text instead. The issue is looked up in the checkout's GitHub repository (its `origin` remote, or another GitHub remote). Add `--github acme/web` for an issue in another repository, or when the checkout has no GitHub remote. ## How it works Four helpers take turns, each with only what it needs: | Helper | Does | | --- | --- | | **Intaker** | Checks that `git`, `gh`, and the agent are ready, reads the issue, and makes the fresh copy of your project. | | **Briefer** | Finds the files that matter and writes what the change should look like, which tests to add, and which checks prove it. | | **Coder** | Writes the change. | | **Tester** | Runs the checks. When they fail, it hands the work back to the Coder or the Briefer with notes, up to two more rounds. | When the checks pass and the issue is still open, Solver commits to a `coder/issue-N` branch, pushes it, and opens the pull request. If the issue looks already done or no longer current, it stops and says why. Merging stays with you. ## Options | Option | Does | | --- | --- | | `--github OWNER/REPO` | The issue's repository (default: this checkout's GitHub remote). | | `--repo PATH` | The checkout to work from (default: this folder). | | `--engine NAME` | What the helpers run on: `claude`, `opencode`, `coder`, or `devin`. | | `--rounds N` | How many times the Tester may hand work back (default 2). | | `--coder-model NAME` | The Coder's model, such as `claude-opus-5-5`. | | `--no-pr` | Stop after the checks; open no pull request. | | `--no-gate` | Work the issue even if it looks already done. | | `--plain`, `--json` | Print the run as text, or as one JSON line per event. | In the next release, `coder solver --help` lists every option. Each run keeps its record and its copy of the project under `~/.openagents/coder/solver-runs/`. Next: [Safety](/docs/coder-safety). --- Source: https://openagents.com/docs/coder-safety # Safety Coder does ordinary coding work without stopping to ask: reading files, editing them, and running commands such as builds and tests. A short list of actions that are hard to undo always waits for you, whichever agent is answering. ## What always waits for you | Action | For example | | --- | --- | | A production deploy | `wrangler deploy`, `gcloud run deploy`, `fly deploy`, `vercel --prod` | | Merging a pull request | `gh pr merge` | | Reading or changing a secret | `gh secret`, `gcloud secrets`, `op read`, reading `.env` files, private keys, or credential files | | A payment | `openagents wallet send`, `lncli`, `bitcoin-cli`, creating charges with `stripe` | | A DNS change | `gcloud dns record-sets` | The same list holds on Claude Code, Codex, OpenCode, and Coder's own loop, and wrapping a command in a shell (`bash -c '…'`) doesn't hide it. Pushing commits is not on the list. ## The approval card When one of these comes up and you're at the terminal, Coder asks you one plain question, such as "Let Claude (Haiku 5.5) merge a pull request?", with the exact command. | Key | Does | | --- | --- | | Y | Allow it, this one time. | | N, Esc | Deny it. | | PageUp, PageDown | Read the whole command. | Either way the agent carries on with the rest of the work. If nobody is there to answer (in a script, for example), the action is held: the agent finishes what it can and hands that step back to you. ## Set the rules for a project A project can tighten these rules in `.openagents/approvals.json` at its root. Each rule is `allow`, `ask`, or `deny`: ```json {"schema": "openagents.approval-policy.v1", "rules": {"pr.merge": "deny", "deploy.staging": "ask"}} ``` The rules are `deploy.staging`, `deploy.production`, `pr.review`, `pr.merge`, `dns`, `secrets`, and `payments`. A file can make merging run freely or refuse it, but it can never lower a production deploy, a secret, a payment, or a DNS change below asking you, because an agent could write that file. ## Your own checks You can add your own checks that run before each step, in the same format as Claude Code's hooks: put them in `.openagents/hooks.json` in a project, or in `~/.openagents/hooks.json` for every project. A check that exits with code 2 blocks the step. Your checks add to the list above; they can't open what it holds. ## Where Coder makes changes - **In the terminal app**, a chat works directly in the folder you opened. Use Git as usual, and `/rewind` to put back the files a turn changed. - **Background agents** (`/agent`), **Solver**, and **chats run from scripts** (`openagents coder chat`) each work in their own copy of the project: a Git worktree on its own branch. The folder they started from is read-only for them; an edit there, or a command that writes there, is refused. - **Everywhere**, commands that throw away uncommitted work are refused, such as `git stash`, `git reset --hard`, `git checkout -- .`, `git restore`, and `git clean -f`. Coder points to a fresh worktree instead. ## Your keys and passwords - Keys you give Coder are kept in files only you can read, under `~/.openagents/coder/`, and are never shown on screen. - Commands Coder runs in the background have keys taken out of their environment and out of everything the chat reads. - Messages that look like they hold a password or key are left out when chats sync to your account, and memory notes refuse them. See also [Privacy and security](/docs/privacy-and-security). Next: [Sync, share, and export](/docs/coder-sync). --- Source: https://openagents.com/docs/coder-sync # Sync, share, and export Coder keeps your chats on your computer. Signed in (`coder login`), it can keep them on your openagents.com account too, so you can read and answer them on the web and on your phone. ## Sign in | To | Run | | --- | --- | | Sign in from the terminal | `coder login`, then approve the code at [openagents.com/device](https://openagents.com/device) | | Sign in from inside Coder | `/login` | | Sign in with a key, without a browser | `coder login --key`, then paste a sign-in key from your account's Settings (or set `OPENAGENTS_TOKEN`) | | Sign this computer out | `coder logout`, or `/logout` in Coder | The website's [Connect your terminal](https://openagents.com/settings/terminal) page walks through the same steps: it shows the install command and a `coder login --pair` command, and you approve the sign-in on that page. ## Turn sync on After you sign in, Coder asks once where this computer's chats should live: **Sync all my chats** or **Keep chats on this computer**. Answer in the terminal or on the website. Change it any time: | Command | Does | | --- | --- | | `/sync on` | Save every chat on this computer to your account, earlier ones too, and keep saving. Memory notes sync too. | | `/sync off` | Stop saving. Chats already on your account stay there. | | `/sync delete` | Remove this computer's chats from your account. | | `coder sync` | Send every chat here now, background agents' chats included (sync must be on). Comes in the next release. | Sync is off until you choose it. A Coder run with its own folder (`--state DIR`) doesn't sync until you turn sync on for that folder. Messages that look like they hold a password or key are never sent. Deleting a synced chat in one place deletes it in the other. ## Read and reply on the web and phone Synced chats appear in the sidebar on [openagents.com](/), marked with this computer's name, and in the phone app's chat list. While Coder is open on that computer, you can reply there: Coder picks up your reply as soon as it's free, shows it in the chat as your message, and answers with this computer's files and commands. The answer appears on the web and phone as usual. When Coder isn't open, the page says so and offers no reply box. To start a new chat inside one of your projects on openagents.com from the terminal, ask Coder ("make a new chat in my finances project") or run `openagents chat send "MESSAGE" --project finances`. It's an openagents.com chat, so it shows in that project on the website and phone. A chat Coder ran in a checkout of a GitHub repository goes under your project for that repository (Projects in the sidebar, and on your phone). Move a chat to another project, or out of one, from its menu on the website or from the terminal: | Command | Does | | --- | --- | | `openagents projects move CHAT PROJECT` | Move a chat into a project. CHAT is its id, the start of its id, or its title; PROJECT its name, repository, or id. | | `openagents projects move CHAT --none` | Take a chat out of its project. | A chat you moved stays where you put it. With sync on, prompts you set up with `/schedule` also show on your account, where you can pause or delete them. ## Save a chat to a file | To | Run | | --- | --- | | Save this chat | `/export`, or `/export PATH` | | Save a saved chat by its ID | `openagents coder export ID --output chat.json` | | List saved chats and their IDs | `openagents coder sessions list` | | Open a chat file to read or continue it | `openagents coder import chat.json` | Exports use ATIF, an open format for agent chats: every message, step, and result, with tokens, cost, and time for each model call. Coder shows the file's path when it's done and copies it when it can. ## Share a chat as a trace A trace is a chat uploaded to your account, which you can look through on the website and, if you choose, share with a link. ```sh coder trace upload --last # your latest chat coder trace upload --last --share # with a public link coder trace list # your traces ``` Passwords, keys, your home folder's name, and email addresses are taken out first. See [Traces](/docs/traces). ## Download everything ```sh coder export --account ``` Saves everything on your account to one file in this folder: your chats (each with a Markdown copy), projects, traces, computers, and settings. Keys, tokens, and passwords are never in it. Next: [Coder from scripts](/docs/coder-scripts). --- Source: https://openagents.com/docs/coder-scripts # Coder from scripts `openagents coder` runs the same chat as the terminal app, without the screen: for scripts, CI jobs, and other agents. It comes with Coder; see [Download and install](/docs/download). Run `openagents coder --help` for every command. ## Send a message ```sh openagents coder chat -p "Explain the files in this folder. Change nothing." ``` The reply prints to standard output. Other ways to give the message: ```sh openagents coder chat --prompt-file task.md echo "What changed in the last commit?" | openagents coder chat --stdin ``` ## Continue a chat Give the chat a name with `--session`, and use it again to continue: ```sh openagents coder chat -p "Add a test for slugify" --session slug openagents coder chat -p "Now run it" --session slug ``` Without `--session`, each call starts a new chat. Chats are saved like the terminal's, so `/resume` in `coder` opens them too. ## Where it works In a Git project, each scripted chat works in its own copy of the project (a worktree in `.coder/worktrees/`, on a `chat/ID` branch), so your checkout stays as it was and several chats can run at once. Add `--in-place` to work in the folder itself, and `--in DIR` to work in another folder. ## Choose who answers | Option | Who answers | | --- | --- | | `--mode auto` | Coder picks, as Auto does in the terminal (the default). | | `--mode coder` | Coder's own loop. | | `--mode codex` | Codex, on this computer's ChatGPT sign-in. | A choice holds for the chat's later messages too; `--mode auto` lifts it. `--instructions TEXT` or `--instructions-file FILE` adds standing instructions for the chat. ## Models These set the model for Coder's own loop. Pick a slug from the list: ```sh openagents coder models list # the models you can pick openagents coder models set openrouter/free # pick one openagents coder models set auto # let OpenAgents pick openagents coder models set SLUG --reasoning low --max-tokens 4000 ``` ## JSON output Add `--json` to stream one JSON object per line as the chat runs (each step, its result, and the reply), ending with a `finished` line that has the reply and the chat's file: ```sh openagents --json coder chat -p "List the TODOs in src/" --session todo ``` ## Ask before acting ```sh openagents coder chat -p "Clean up the build scripts" --approvals stdin --json ``` With `--approvals stdin`, any command that isn't read-only waits: an `approval` line appears in the output, and you answer by writing `confirm ID` or `reject ID` to standard input. ## Hand work to another agent ```sh openagents coder delegate --to codex --task "Review the last commit for bugs" --read-only openagents coder delegate --to claude-code --task "Write tests for src/parse.rs" ``` `--to` takes `claude-code`, `codex`, `opencode`, `coder`, `auto`, or any agent ID from `openagents coder agents list`. `--model` picks its model. It prints the agent's short result. ## Everything else | Command | Does | | --- | --- | | `openagents coder status` | Who answers, the model, plugins, and the folder. | | `openagents coder plugins list` | Plugins, and whether each is on. `enable ID` and `disable ID` change one. | | `openagents coder agents list` | Agents found on this computer. `enable ID`, `disable ID`, `refresh`. | | `openagents coder sessions list` | Saved chats. `read ID` prints one; `delete ID` removes one. | | `openagents coder export ID` | Save a chat as a file. | | `openagents coder memory list` | What Coder remembers here. `memory instructions` lists the instruction files it reads. | | `openagents coder trace upload --last` | Upload the latest chat as a trace. | `--state DIR` keeps Coder's data in another folder, so a script doesn't touch your own settings and chats. Keys come only from environment variables (such as `OPENROUTER_API_KEY`) or configuration on standard input, and are never printed. ## The openagents command `openagents` does more than Coder: chat with OpenAgents, change settings, work with GitHub issues, connect a phone, and call models on the OpenAgents API. Run `openagents --help` for the list, and see [The openagents command](/docs/cli). Next: [Coding agents](/docs/coding-agents). --- Source: https://openagents.com/docs/coding-agents # Coding agents Coder runs the coding agents you already use, on your computer, under your own sign-in with each one. This page covers Coder tasks started from the Mac app, OpenAgents Terminal, the phone, or `openagents chat`; for the `coder` terminal app, see [Choose who answers](/docs/coder-agents). | Agent | Order | Model when you don't name one | | --- | --- | --- | | Codex | First | `gpt-6.1-sol`, medium reasoning | | Claude Code | Second | `claude-opus-5-5` | | Grok Build | Third | Grok Build's own default | | Devin CLI | Fourth | SWE-2 Medium | | OpenCode | Fifth | The model OpenCode's own configuration names | Every agent signed in on this computer is on, with nothing to enable. Coder tries them in order and uses the first one that is signed in and has room in its usage window. Devin CLI bills its own paid API for each run; turn it off if you don't want Coder to use it. ## Sign in Each agent is signed in with its own program, on the same computer and as the same user that runs Coder: 1. Install the agent's command-line program. Codex: `npm install -g @openai/codex`. Claude Code: `npm install -g @anthropic-ai/claude-code`. OpenCode: see [opencode.ai](https://opencode.ai). Grok Build and Devin CLI install from their makers' own instructions. 2. Run it once in a terminal (for example `codex`, `claude`, or `opencode`) and sign in. 3. Check: the Mac app's sidebar and **Settings → Coder** say **Signed in** for it, and OpenAgents Terminal lists it under **Agents**. Coder only checks whether each agent is signed in. It never reads or sends your sign-in itself. ## Ask for one Name the agent in your message: "run this with Claude Code", "do it with Codex". Coder puts that agent first for the run, unless you turned it off on that computer. If it can't use it, because it isn't signed in, is turned off, or has no room right now, the start says why and names the one running instead. This works from the phone too. In the `coder` terminal app, `Shift+Tab` and `/models` choose the agent and its model; see [Choose who answers](/docs/coder-agents). The Mac app and OpenAgents Terminal have no model picker yet. To choose a model there, name it in the settings (`codex:MODEL`, `opencode:PROVIDER/MODEL`); see the [settings reference](/docs/settings). ## Failover If an agent turns Coder away during a run, Coder records it and switches to the next agent, and the chat says it switched. An agent turned away earlier is skipped until it has room again. ## Turn an agent off, or change the order Every signed-in agent is used unless you turn it off. - **Mac app:** **Settings → Coder → Agents Coder may run.** Turn one off to keep Coder from using it. At least one stays on. - **OpenAgents Terminal:** `/settings`, the same switches. - **Anywhere:** `openagents settings disable devin` (and `enable devin`). `openagents settings set coder.providers claude,codex` puts Claude Code first; agents you leave out still follow. Delegated sessions show inside their Coder chat: when a task hands work to OpenCode or Devin CLI, that session appears as a row you can open. Separate Codex, Claude Code, OpenCode, and Devin CLI sessions aren't listed in the chat list; in the Mac app, **Saved sessions** shows your Codex and Claude Code sessions. Next: [Watch, steer, and stop Coder](/docs/following-coder). --- Source: https://openagents.com/docs/following-coder # Watch, steer, and stop Coder A Coder run lives in its chat. You can follow it, add to it, answer it, or stop it from the Mac app, the Terminal, the `openagents` command, or your phone. ## Follow along - The run's first card names the coding agent, the model, why that agent, and the project. - Each step shows as a short line: reads and searches fold into one row ("Read 3 files, Searched 2 patterns"); each command or edit has its own row with its result. Click a row on the Mac, or press `Ctrl+O` in the Terminal, to see it in full. - The working line shows the step, Jev's estimate of how much is done, and the time: "Coder is working · step 5 · ≈40% done · 9s". - On the phone, the Coder card shows how long Coder has worked and, at the end, how the run ended. Closing the app or the Terminal doesn't stop the run. Open the chat again and it follows the run from the start. From a shell: `openagents chat follow --thread ID`. ## Send more while it works - **Send** while Coder works queues your message for its next turn. On the Mac, the queue shows each message with **Send now** and **Remove**; on the phone, **Edit queue** changes what's waiting. - **Stop and send** stops the current turn and continues with your message. - **Steer now** sends it before the next turn starts. On the phone, long-press send to choose between these. ## Answer a question When Coder asks a question, or asks to go ahead with a step, it shows as a card in the chat. Answer by typing in the chat (on the Mac, an approval also has **Approve** and **Deny**). Your answer is information for Coder; it never widens what Coder may do. ## Follow up after it finishes A message after a run finishes goes to OpenAgents with what the run did. A question such as "what did you change?" is answered in the chat. A request for more work, such as "now add a test", continues the same task, in the same copy of your project. ## Stop it - **Mac app:** **Stop Coder**. - **Phone:** **Stop** on the run, or the stop button in its chat. - **Terminal:** Esc or `/stop`. - **Shell:** `openagents chat stop --thread ID`. The run ends as stopped, and the chat says so. Its work so far stays in its copy of your project. Next: [Worktrees and changes](/docs/worktrees-and-changes). --- Source: https://openagents.com/docs/traces # Traces A trace is a record of an agent run: what you asked, what the agent said, and each step it took, such as a command it ran, with the result. Coder keeps every chat as one, in the open ATIF format. Upload a trace to your openagents.com account to keep it, look through it on the website, or share it with a link. ## Upload a trace Sign Coder in to your account once: ```sh coder login ``` Then upload your latest chat: ```sh coder trace upload --last ``` Or a chat by its id, or any ATIF file: ```sh coder trace upload SESSION_ID coder trace upload --file run.json ``` `openagents coder sessions list` shows your chats and their ids. `openagents coder trace …` runs the same commands. Before anything leaves your computer, Coder takes out passwords, API keys, tokens, your home folder's name, and email addresses, and tells you how many it took out. The website checks again and refuses a trace that still looks like it holds a key. Coder prints the trace's address when it's done. Uploading the same trace twice keeps one copy. A trace can be up to 8 MB, and your account keeps up to 100. ## Upload a session with its agents A session that started other agents uploads as one trace with every agent under the one that started it. To upload a Claude Code session, give its id, its `.jsonl` file, or its folder: ```sh coder trace upload --claude-session 3ba359c8-4ac9-42a6-a8e7-2e08994e591e ``` Coder reads the session and its agents from `~/.claude/projects`, takes out keys and personal details the same way, and shortens very long command output so each agent fits in 8 MB. A trace keeps up to 1,000 agents. If some agents don't upload, run the same command again: what's already there is kept, and only the rest is sent. A Coder chat that ran agents uploads the same way with `--last`. The trace's page shows its agents as a tree under **Agents**: each one with how long it ran, the tokens it used, and about what it cost at list prices, on a shared timeline. Open an agent on [your traces](https://openagents.com/traces) to read its own steps. Sharing the trace shares its agents too. ## See and share your traces ```sh coder trace list ``` On the website, open **Settings → Traces**. A trace is private: only you can see it, signed in. Open it and choose **Share** to get a public link at `openagents.com/trace/…` that anyone can open; **Stop sharing** turns the link off. To share as you upload: ```sh coder trace upload --last --share ``` **Delete** removes a trace from your account, and its link with it. --- Source: https://openagents.com/docs/worktrees-and-changes # Worktrees and changes A Coder task started from the Mac app, OpenAgents Terminal, the phone, or `openagents chat` never works in your checkout. Each task gets its own Git worktree: a separate folder with a copy of your project at its last commit. Your files, your branch, and any uncommitted changes stay as they were. (In the `coder` terminal app, a chat works in the folder you open; see [Safety](/docs/coder-safety).) ## Where the work is - A task's worktree starts from your checkout's current commit (`HEAD`). Uncommitted changes in your checkout are not carried over, so commit what Coder should see first. - Worktrees live in `~/.openagents/worktrees/`. When a run finishes, the chat names its worktree and the files it changed, with lines added and removed. - A follow-up that asks for more work continues in the same worktree. - Stopping a run, or a run that fails, leaves its worktree as it was, so you can look at it or pick up from there. ## Review the change When a finished task recorded its change, the chat shows a **What changed** card. 1. The card opens on a click, and the diff shows in a pane on the right (on the phone, in the chat). The pane is read-only. 2. The card names the exact commits it shows. If the worktree changes while you look, the card says the view is out of date and offers **Refresh**. ## Publish the change **Publish** on the card commits exactly the change you reviewed and pushes it: - By default, to a new `coder/review-…` branch, with a draft pull request opened through the GitHub CLI (`gh`). - If the repository's `.openagents/coder-issues.json` says `"land": "main"`, onto that branch directly, fast-forward only. The card then links the pull request or the commit. Publish is refused if the worktree moved past what you reviewed; refresh and look again. ## Bring a change into your checkout yourself The worktree is an ordinary Git worktree. From your checkout you can, for example, look at it with `git -C PATH diff`, or commit there and cherry-pick the commit. Next: [Work on a GitHub issue](/docs/github-issues). --- Source: https://openagents.com/docs/github-issues # Work on a GitHub issue Ask Coder to work an issue and it takes the issue from claim to close: it reads the issue, does the work, runs your checks, lands the change, and reports on the issue. ## Before you start - Run `coder` in a checkout of the issue's repository. - Install the GitHub CLI and sign in: `gh auth login`. ## Ask for it In a chat on the Mac, in the Terminal, or from a shell: ```sh openagents chat "work on #10051" ``` "Take OpenAgentsInc/openagents#10051" works too. ## What Coder does 1. **Claims it.** Reads the issue, its comments, and a few issues it links, and posts a comment saying Coder is working on it. 2. **Works.** Starts from the latest default branch (`origin/main`), in its own worktree, with the issue as its task. 3. **Checks.** Runs your repository's checks for what it changed: the tests of each package it touched, plus checks for style and broken links. If they fail, it fixes and checks again, a few rounds at most. 4. **Lands.** Commits with the issue's title and a link, then either opens a pull request that closes the issue (the default) or rebases and pushes to `main`, as the repository says. 5. **Closes.** Comments the commit, the files, the checks it ran, and the agent it used, and closes the issue. It never pushes a change whose checks fail. If it can't finish, it comments what it tried and the failing output, releases its claim, and leaves the issue open with the change in its worktree, so you can pick up from there. ## Keep it running The issue flow runs in the program that started it. Keep the Terminal screen or the command open until it lands; if you close it partway, the claim stays without a closing comment. Esc, Ctrl-C, or **Stop** stops it and says so on the issue. ## Several issues ```sh openagents chat work --issues 10052,10053 # one after another openagents chat work --issues bug --parallel 2 # a label's open issues, two at once ``` Each issue gets its own thread and worktree. Coder skips closed issues and issues someone claimed recently. ## The repository's policy A file at `.openagents/coder-issues.json` tells Coder how to land: ```json { "land": "main", "claim_hours": 6, "fix_rounds": 3, "fmt": true, "clippy": true } ``` Without the file, Coder opens a pull request and runs the tests and the diff checks. `--land main` or `--land pr` overrides it for one command. Next: [Ship an iPhone build from your phone](/docs/ship-from-your-phone). --- Source: https://openagents.com/docs/ship-from-your-phone # Ship an iPhone build from your phone You can ask Coder, from your phone, to build an iPhone app on your Mac and upload it to TestFlight. Then you install the new build on the same phone. This is how we ship OpenAgents for iPhone: build 44 was made and uploaded from the phone. It works for your own app too, if its repository has a release script and says how to use it. ## What you need on the Mac - OpenAgents for Mac, with your phone [connected](/docs/connect-a-computer), the app's repository picked as the project, and **Let my phone start Coder here** on. - A coding agent signed in. See [Coding agents](/docs/coding-agents). - Xcode, with your Apple Distribution signing identity in the login keychain and the App Store profile installed. - An App Store Connect API key in a file on the Mac. The OpenAgents repository reads it from `~/work/.secrets/appstoreconnect.env` by default (`ASC_API_KEY_ID`, `ASC_API_ISSUER_ID`, `ASC_API_PRIVATE_KEY_PATH`). - Coder's default full access (`coder.access` set to `full`), so the build can use the keychain and Xcode. ## Tell Coder how to ship Coder's agents read the repository's `AGENTS.md`. Say there how a release works. The OpenAgents repository says, in short: 1. Raise the build number in `bins/openagents-ios/host/project.yml`. 2. Add that build's entry at the top of the app's changelog. 3. Commit and push to `main`. 4. Run `scripts/release/testflight.sh start`, then run `scripts/release/testflight.sh wait` again and again until it says it's done or failed. Each `wait` returns within a few minutes, so no single command runs too long. 5. Report the build number and the script's last line. The script refuses a checkout with uncommitted changes and a build number App Store Connect already has. `--validate-only` does a dry run: it builds and validates the app without uploading. ## Ship 1. On your phone, open a chat and say what to ship: "Ship build 45 to TestFlight with the new chat menu in the changelog." 2. Coder starts on the Mac. Follow its steps in the chat; a release takes 15 to 25 minutes. 3. When Coder reports the build is in TestFlight, open TestFlight on the phone and install it. 4. In the app, **Account → Changelog** shows the new build first. If something fails, Coder reports the script's last line. Ask it to fix the cause and try again in the same chat. Next: [Connect a computer](/docs/connect-a-computer). --- Source: https://openagents.com/docs/connect-a-computer # Connect a computer When a computer is connected to your openagents.com account, its Coder chats show on the website, in the left panel, where you can reply to them. ## Connect it to your account 1. Install Coder on the computer. On macOS and Linux: ```sh curl -fsSL https://openagents.com/cli/install.sh | bash ``` On Windows, in PowerShell: `irm https://openagents.com/cli/install.ps1 | iex` 2. Run `coder login`. It shows a code. 3. Approve that code at [openagents.com/device](https://openagents.com/device). 4. In Coder, type `/sync on`. Coder's chats on that computer then show in the website's left panel. A reply you send from the site reaches Coder while it's open on that computer. [Settings](https://openagents.com/settings) lists your signed-in computers, each with **Remove**. ## Let an agent sign in as you An agent, a script, or a sandbox can sign in without a code to approve. Make a key at [Settings, Sign-in keys for agents](https://openagents.com/settings/sign-in-keys), copy it (it's shown once), and give it to the agent in one line: ```sh OPENAGENTS_TOKEN=oa_sk_... coder ``` To save it on a computer instead, run this and paste the key when asked: ```sh coder login --key ``` Anyone with the key can act as you, so keep it secret. Revoke it in the same Settings page, or from a terminal with `openagents keys revoke NAME` (`openagents keys list` shows your keys). ## Connect your phone Get [OpenAgents for iPhone](/docs/iphone) on TestFlight at [testflight.apple.com/join/dvQdns5B](https://testflight.apple.com/join/dvQdns5B). Connect your phone to a computer once, and the phone can reach it from anywhere: chat with it, run Coder in your projects, and open a terminal on it. 1. Install Coder on the computer (above). It adds the `openagents` command. 2. Start the computer's host and leave it running: `openagents host serve --iroh --control` 3. In a second terminal, run `openagents connect invite`. It draws a QR code. 4. On your phone, open **Account**, then **Computers**, then **Connect a computer**, and scan the code. 5. Both the terminal and the phone say the computer is connected. There is no key to copy, and you don't need Tailscale. The code works once, for one phone, and stops working when the command ends. ## Can't scan? Run `openagents connect invite --text` instead. It prints a code under the QR code; paste it in the phone's **Paste a code**. ## A computer you reach over SSH From a computer that has `openagents`, run `openagents connect --ssh me@box`. It installs and starts everything there and pairs the two. See [The openagents command](/docs/cli). ## How the phone reaches the computer The phone connects straight to the computer when it can, and through the OpenAgents relay when it can't, so it works on the same Wi-Fi and on mobile data. If you already use Tailscale, it can be another route; it's never required. See [Manage computers](/docs/manage-computers). ## What a connected phone can do A connected phone has full access to that computer: it can chat through it, run Coder in your projects, open a terminal, and see the phones connected to it. To take a phone's access away, run `openagents connect remove DEVICE` on the computer (`openagents connect devices` lists them). Next: [Manage computers](/docs/manage-computers). --- Source: https://openagents.com/docs/manage-computers # Manage computers ## On the website [Settings](https://openagents.com/settings) lists the computers signed in to your account, each with **Remove**, which signs it out. To add one, run `coder login` on it; see [Connect a computer](/docs/connect-a-computer). ## On your phone In [OpenAgents for iPhone](/docs/iphone), **Account → Computers** lists your computers, each with a one-word status. - **Each computer** opens on a tap: its status, ordering work, a terminal on it, its access, and its recent work. - **Its menu** switches it off or on, tries it now, opens its access, or forgets it. **Forget** stops this phone connecting and drops the computer from the list; the computer keeps the phone's access until you remove it there. - **Connect a computer** opens the scanner, and **Add another way** takes a pasted code. See [Connect a computer](/docs/connect-a-computer). ## What your phone sees of a computer - **Its chats.** The computer's own chats (from the Mac app, the Terminal, or `openagents chat`) show in the phone's earlier chats, labelled with the computer. Open one and keep going; the computer answers. After a relaunch with the computer off, they still list, marked **Last read …**. - **Coder's work** on it, step by step, while it runs and after. - **Its coding agents.** Ask in a chat "which coding agents are connected?" and the reply names the agents on your computer. - **Its plugins.** Ask "list my plugins" and tap **Run** on the card. ## On your Mac **Phones and computers** in the Mac app shows: - **Online. Your phone can reach this Mac.** or **Offline.** - The phones that can reach this Mac, each with **Remove**, which cuts it off at once. - Your project for Coder (**Choose folder…**), whether each coding agent is signed in, and **Let my phone start Coder here**. - Coder's recent work, and **Connect another phone**. On a computer without the Mac app, `openagents connect devices` lists the phones and `openagents connect remove DEVICE` removes one. Only the computer itself can let phones start Coder on it: the Mac app's switch, or a command run on that computer. No phone or relay message can turn it on. ## When a computer is offline Messages to Coder on that computer wait on your phone, encrypted, and go out as soon as the computer answers again. A relaunch or a bad connection never sends one twice. ## Tailscale You don't need Tailscale. If you already use it, **Account → Tailnet** can sign the app in to Tailscale to list your tailnet's devices. That sign-in grants no access to any computer: access only ever comes from pairing. Next: [Plugins](/docs/plugins). --- Source: https://openagents.com/docs/plugins # Plugins A plugin is anything you add to OpenAgents. You write one, test whether it helps Coder, and publish it so other people can check your result and use it. ## What a plugin contains A plugin can have any of these parts: - **Skills.** Instructions the agent reads before a task. A skill runs no code. - **Workflows.** Typed, step-by-step programs that OpenAgents runs: look things up, check, decide, or run Wasm. - **Knowledge.** Cited reference entries, such as a method, an edge case, or how a command is used. - **Wasm.** Sandboxed code that does one bounded job, such as reading a failing command's output. It is the only code a plugin can carry. It runs with no network, on a fixed budget of instructions and memory, and reads only the files its workflow grants. A workflow runs it; the model never calls it by name. - **Tests.** Tasks Coder runs with the plugin and without it, and the checks on each run. Not every plugin has every part. A plugin made in chat is a single skill. ## Plugins built into Coder | Plugin | What it does | | --- | --- | | Claude Code | Coder hands a task to Claude Code on your computer and shows its progress as it works. | | Codex | Coder hands a task to Codex on your computer and shows its progress as it works. | | Cursor | Coder hands a task to Cursor's agent on your computer and shows its progress as it works. | | Grok Build | Coder hands a task to Grok Build on your computer and shows its progress as it works. | | OpenRouter | Use OpenRouter models in Coder with your own API key. | Coder finds each coding agent when it's installed on your computer. In the [Terminal](/docs/terminal), `/plugins` turns each plugin on or off. ## Why plugins OpenAgents is an open network of agents: one conversation in front, many specialized parts behind it. Anyone can add a part, and a part only becomes one of Coder's defaults after it was measured with and without, rerun by other people, and shown to help on someone else's tests. The argument is in [The Return of the General Agent](https://github.com/OpenAgentsInc/openagents/blob/main/docs/essays/2026-10-01-the-return-of-the-general-agent.md). You can also ask in any chat which plugins there are, and asking for something no plugin does yet offers **Add a plugin**. Next: [Write a plugin](/docs/write-a-plugin). --- Source: https://openagents.com/docs/write-a-plugin # Write a plugin There are two ways to make a plugin: in chat, or as a directory of files. ## In chat In the OpenAgents app, ask "Help me make a plugin that ...". We draft the plugin and its tests with you one step at a time, try it once, and then offer to run the full tests on our computers. A plugin made in chat is a skill. A plugin that needs new code goes to Coder on a computer you connected. ## As files A plugin with code lives in one directory: | File | Part | | --- | --- | | `src/lib.rs` | The Wasm: one operation, written in Rust against `plugin-pdk`. | | `programs/NAME.json` | The workflow: the steps that hand the Wasm your request and say which files it may read. | | `package.json` | The plugin's record: its name, a one-line summary, the publisher's key, and the workflow it uses, pinned by hash. | | `evals/` | The tests: tasks where it should help, and one or two where it should stay out of the way. | To make one, in a checkout of the [openagents repository](https://github.com/OpenAgentsInc/openagents): 1. Create `crates/plugin-NAME` with that layout. The `crates/plugin-*` directories already there are the test runner's fixtures and show the shape. 2. Write your operation in `src/lib.rs`. Native tests run it against files in memory, in a second. 3. Add `NAME` to `scripts/build-plugin-guests.sh` and run `./scripts/build-plugin-guests.sh NAME`. It builds the Wasm, puts it in the workflow, and updates the hash in `package.json`. 4. Try it once on a project, with reads only: `openagents plugin run crates/plugin-NAME --in PROJECT --request "..."`. The `openagents` command is built from the same repository (`cargo build --release -p openagents-cli`). ## Good habits - **Grant the least you can.** Name the files the Wasm reads. A grant holds at most 1,024 files, and one call reads at most 64 KiB. - **Write the summary as a request.** The workflow's summary is what Coder reads when it decides whether a request is for your plugin. - **Say what you couldn't do.** Report what the plugin read, what it left out, and what it couldn't check, rather than guessing. Skills are Markdown files in `skills/` (`skills/NAME.md`), and knowledge entries are published with `openagents kb publish`. The full guide is on [GitHub](https://github.com/OpenAgentsInc/openagents/blob/main/docs/plugins/README.md). Next: [Test a plugin](/docs/test-a-plugin). --- Source: https://openagents.com/docs/test-a-plugin # Test a plugin A test shows whether a plugin helps. Coder does the same tasks twice: once with the plugin and once without it. Each test is a task (a prompt and the files it starts with) and the checks on what the run did. ## Run the tests On a computer, from the plugin's directory: ```sh openagents plugin test init # write the tests with us, step by step openagents plugin test run . --runs 1 # try each test once openagents plugin test run . # the full run: three times with, three without ``` Write at least four tests where the plugin should help and one or two where it should stay out of the way. Check for facts that are only in the test's files, never in the prompt, so a run without the plugin can't pass by repeating the question. Every run happens in a fresh sandbox that starts with the test's files and nothing else. Nothing leaves your computer until you publish. ## What the result means A result reads like "passed 7 of 7 with it, 2 of 7 without", with one of three verdicts: - **Better.** With the plugin, Coder passed more tests, still passed every test where the plugin should stay out of the way, raised the average score by more than runs of the same setup vary, and wasn't much slower or costlier. - **Worse.** With the plugin, Coder passed fewer tests, or failed a test where the plugin should have stayed out of the way. - **No clear change.** Anything else. With one run each way, the verdict is always this, because there's no way to tell a change from noise. Faster or cheaper never makes a plugin **Better** on its own; it's noted beside the verdict. ## What our computers can and can't see When a plugin you made in chat is tested, it runs on our hosted runner: - It runs only plugins made in chat. - Coder there can't run commands or use the network, so **without a plugin it can't read what's in the test's files.** A test whose answer is in the files fails without the plugin. That is a real difference, but it is bigger than the same comparison on a computer with a shell. - Both runs include Coder's defaults, so a result says what the plugin adds on top of them. - A test set run there has 8 tests or fewer, each run up to three times with the plugin and three times without. Next: [Publish and share](/docs/publish-and-share). --- Source: https://openagents.com/docs/publish-and-share # Publish and share Publishing makes a plugin's test result public, so other people can rerun it, build on it, and use the plugin. ## Publish a result ```sh openagents plugin test publish evals/results/TIMESTAMP/report.json ``` On the phone, it's **Add to the Gym**. Publishing puts two signed records on Nostr, the open protocol OpenAgents runs on: your test set, released under your key, and your result. A result is public whatever it says, **Worse** included. There is no review queue. Nobody approves a plugin, a test set, or a result before it's published; anyone with a key can publish, and what decides whether a plugin is used is what other people's runs show. Today the `openagents` command publishes your test set and your result, not the plugin's own release. Our hosted runner releases the catalog plugins it tests, which is how the three example plugins were released. Publishing a plugin's release from your own computer is designed but not built yet. ## Checks Anyone else can rerun your tests on your plugin: `openagents plugin test check RESULT_ID` (in the app, **Check a result**). A check publishes its own result that confirms yours when the verdicts match and disputes it when they don't. Both stay visible. ## Validation A check reruns *your* tests. A validation answers whether your plugin only does well on tests you wrote: someone other than you writes a second test set, releases it after your plugin's release (`openagents plugin test release`), runs it, and publishes the result with `--validates RESULT_ID`. It counts when it is **Better**. ## Adoption into Coder A plugin becomes a candidate for Coder's defaults, the plugins Coder uses for everyone, when its result is **Better**, at least three checks by different people confirmed it, and at least one validation is **Better**. Adoption is then a decision an OpenAgents operator signs, never automatic. Computers pick up the defaults with `openagents plugin defaults sync`, and our hosted runner reads them on each run. This has happened once, on 2026-09-29. Every key in that record came from one machine and one operator, which the [record](https://github.com/OpenAgentsInc/openagents/blob/main/docs/extensions/measurements/2026-09-29-first-adoption.md) says. ## Credit Credit is XP and your name, not money. It comes from two events only, and each quest sets the amounts; in the current quests: - **Someone reruns your result to protocol.** The checker earns 50 XP, the original tester 25, and the test set's author 25, whether the check confirms or disputes. - **Your plugin is adopted.** Its author earns 200 XP, the author of the tests that showed it 100, and each tester whose result was confirmed 50. Running, publishing, viewing, or downloading earns nothing. XP can't be spent, transferred, or converted. Your profile in the app shows what you made and the XP it earned. ## On the map In OpenAgents for Mac, the **Map** page shows each plugin and the step it has reached: Not packaged, Candidate, a verdict, Reproduced, Validated, or Adopted, with the next step for each. See [Decks and the Map](/docs/decks). The specifications are on GitHub: [testing and publishing](https://github.com/OpenAgentsInc/openagents/blob/main/docs/extensions/evaluation.md), and the protocols for [plugins](https://github.com/OpenAgentsInc/openagents/blob/main/nips/openagents/NIP-EXT.md), [results](https://github.com/OpenAgentsInc/openagents/blob/main/nips/openagents/NIP-EVAL.md), [workflows](https://github.com/OpenAgentsInc/openagents/blob/main/nips/openagents/NIP-PRG.md), [knowledge](https://github.com/OpenAgentsInc/openagents/blob/main/nips/openagents/NIP-KB.md), and [XP](https://github.com/OpenAgentsInc/openagents/blob/main/nips/openagents/NIP-XP.md). Next: [The Gym and XP](/docs/gym-and-xp). --- Source: https://openagents.com/docs/gym-and-xp # The Gym and XP The Gym is where plugins are tested on Coder: the same tests with the plugin and without it, so anyone can see whether it helps. It lives in the chat, and its results also stand on boards in the Verse. ## In the chat On the phone's Chat menu, tap a starter, or ask in any chat: - **What's new.** The Gym's news, from published results, checks, our changelog, and our notes. - **Check a result.** Rerun another trainer's published result. If you get the same verdict, your check confirms it; otherwise it disputes it. You can't check your own result. - **Make a plugin.** Say "Help me make a plugin that …" and we draft it and its tests with you. See [Write a plugin](/docs/write-a-plugin). **Add to the Gym** publishes a result. The sheet shows exactly what becomes public before anything does. ## In the Verse The Gym building stands straight ahead of where you start in the Grid. Its boards show published results by test set, with the checks on each, and our earlier coding results step by step. **See the board** under a plugin's result in chat walks you there. See [The Verse](/docs/verse). ## XP XP is a record of work other people used. It isn't money: it can't be spent, sent, or exchanged. You earn XP when: - **Someone checks your result to protocol.** The checker earns 50 XP, the trainer who ran the result 25, and the test set's author 25, whether the check confirms or disputes. - **Your plugin is adopted** into Coder's defaults. Its author earns 200 XP, the author of the tests that showed it 100, and each tester whose result was confirmed 50. These are the amounts in the current quests. Running, publishing, or viewing earns nothing by itself. **Tutorial quests.** Six quests each repeat one of our published coding results on your own computer and pay 50 XP each, once per person. They need a desktop computer with Docker and the command line, and a run costs about a cent. The season closes 2026-12-25. **Playtest XP** is separate: it comes from accepted feedback and bug reports during the playtest, and shows beside your trainer XP. ## Your trainer card and level **Account → Trainer** on the phone is your trainer card: your level, XP, the XP to the next level, titles, and the awards behind them. Everyone starts at level 1; level 2 comes at 100 XP, level 3 at 283, and level 4 at 520. Anyone can recompute your level from the signed records on our relay. - **Show my level** lets other players see it over your head in the Grid. **Hide my level** takes it down. - **Export card** signs your card and shares it. - **Link a key** lets XP earned on a computer count toward your level: tap it, enter the computer key's npub, then run `microcoder xp link --relay wss://relay.openagents.com --trainer YOUR_NPUB` on the computer. Neither secret key moves. The menu's **Profile** shows what you made and the XP each item earned. Next: [The Verse](/docs/verse). --- Source: https://openagents.com/docs/verse # The Verse The Verse is a shared world. Its first place is the Grid: a floor of white lines where other players walk around live, with a ball, a stack of blocks, dominoes, and the Gym. There's no chat in the Grid. See [The Grid](/docs/the-grid) for a picture. ## On your phone Open the globe tab in [OpenAgents for iPhone](/docs/iphone). - **Walk:** push the faint stick at the bottom left. - **Look:** push the stick at the bottom right, or drag anywhere. Both thumbs work at once. - **Jump:** double-tap. - **Zoom:** pinch. Pinch in past the nearest view for first person. - **Motion look:** the button between the sticks switches to a camera that follows the phone. The crosshair button recenters the camera. ## On your Mac Click **Verse** in the sidebar's footer of [OpenAgents for Mac](/docs/mac). **Watch** shows the Grid live from above; nobody sees you. **Play** puts you in it, in the same world as the phones. - **W** and **S** move forward and back; **A** and **D** (or **Q** and **E**) step sideways. **Space** jumps; **Shift** sprints. - Hold the right mouse button to look and turn; hold the left to orbit. The wheel zooms, into first person and back. - A click on a board in the Gym opens it. **Esc** closes a board, then releases the mouse. - **Full screen** (F11, or Ctrl+Cmd+F) hides everything but the world. The Verse page is on macOS and Linux, not Windows. **Reduce motion** in Settings keeps the watching camera still. ## In your browser [Everglade](/everglade), a forest glade with a small workshop, runs on this site with nothing to install. Its first download is large; your browser keeps it after that. Move and look as on your Mac. ## Shared things Walk into the ball to push it; it rolls with real physics. Everyone shares the ball, the blocks, and the dominoes, and finds them where they were left. Walking into the pillar to the right of where you start puts them all back. What other players see can lag a little. ## Who sees you While you're in the Grid, the app shares only your avatar's position and the shared things. Other players see a name tag of your key's first eight characters, and your level if you chose to show it. Leaving the Verse tab or page closes the connection. The Grid signs with your world key, never your device key. Lagrange 1, a construction station zone, has a portal site in the Grid, but it's closed for now. Next: [The Grid](/docs/the-grid). --- Source: https://openagents.com/docs/the-grid # The Grid The Grid is the OpenAgents Verse world: a floor of white lines with the Gym building, a ball, and scattered blocks, where other players walk around live. The Mac app shows it on its **Verse** page, and the Verse tab in the iPhone app puts you inside it. ![The Grid, the OpenAgents Verse world, seen from above: the Gym building, a ball, and scattered blocks on a floor of white lines.](/static/verse-grid.jpg) The Grid seen from above, as the Mac app's Verse page shows it. Read [The Verse](/docs/verse) for how to move around and what's there. Next: [Wallet](/docs/wallet). --- Source: https://openagents.com/docs/wallet # Wallet The iPhone app's Wallet tab is a bitcoin wallet on mainnet, with its keys on your phone. It runs on Breez's Spark SDK. It's real bitcoin, so keep amounts you'd be comfortable carrying in a phone wallet. The wallet is in the phone app only (iPhone, and Android in testing). The Mac app, the Terminal, and the website have none; asking a computer's chat to open your wallet says where to find it. ## Receive Tap **Receive** on the [Wallet tab](/docs/iphone). You get a payment request with a QR code, **Copy**, and **Share**, and you can set an amount. Under **Advanced → Other ways to receive** are a Lightning invoice, your Spark address, a Bitcoin deposit address, and your npub, with a switch that publishes your Spark address in your Nostr profile so people can pay your npub. On-chain deposits are added to your balance automatically once they confirm. A receiving Lightning address of your own isn't available yet. ## Send Tap **Send** on the [Wallet tab](/docs/iphone), then paste or scan what you're paying: a Lightning invoice, a Lightning address, an LNURL code, an npub, or a Spark or Bitcoin address. Enter an amount if it needs one. A confirm screen shows the amount and the fee, and nothing is sent until you confirm. On-chain withdrawals offer three speeds. ## Buy bitcoin **Advanced → Buy bitcoin** pays with dollars through MoonPay or Cash App, which open their own page. ## Back up and restore Your wallet's backup is its recovery words. 1. Until you've written them down, the Wallet shows **Back up your wallet**. 2. **Show recovery words** reveals them behind a warning. Write them down and keep them offline. 3. To restore, enter 12 or 24 words. No one from OpenAgents will ever ask for your recovery words. Anyone who has them has your bitcoin. The **Exit backup** under Advanced saves the state you'd need to withdraw on-chain if Spark's operators were down, and exports it to Files. Running an exit from that file is a later recovery feature. ## Agent payments An agent on one of your computers can ask your phone to pay an invoice. The request shows as a **Payment request** sheet: the computer, the task, the purpose, who's paid, the amount, the fee, and what that computer's grant has left. Nothing pays until you tap **Approve**; above ₿1,000, Approve asks for Face ID or your passcode. **Deny** refuses it, and **Stop payment requests** stops that computer asking. **Advanced → Agent payments** lists the requests and which computers may ask. ## Amounts Amounts show as whole numbers of the smallest unit: ₿1 is what was called a satoshi, so 0.00010000 BTC shows as ₿10,000. **Show amounts as** under Advanced switches to the BTC form. ## Who you rely on Spark's operators are run by Lightspark, Breez, and Flashnet. Two must cooperate for payments off the chain, and your safety depends on at least one of them having deleted old keys, which no one can check. If the operators stop, you can still withdraw on-chain yourself, though it can take days and needs a separate on-chain fee. The **i** button in the Wallet shows this note. Next: [Decks and the Map](/docs/decks). --- Source: https://openagents.com/docs/decks # Decks and the Map OpenAgents for Mac can show a slide deck full screen, and a map of how OpenAgents routes every message. ## Open a deck In a chat on the Mac, ask for it by name: - "Show the Test-Time Capabilities deck" - "Open the Three DevDays Later deck" The deck opens over the window. Three decks ship with the app today: Three DevDays Later, Test-Time Capabilities, and OpenAgents, from episode 289. | Key | Does | | --- | --- | | Right arrow, Page Down, Space | Next slide | | Left arrow, Page Up | Previous slide | | Home, End | First slide, last slide | | F | Full screen on or off | | Esc | Leave full screen, then close the deck | The buttons along the bottom do the same, with a slide counter. Some slides are live: the Grid behind a title, the Map you can drag and zoom, or link cards that open in your browser when clicked. Decks open only in the Mac app. Asked on the phone or in the Terminal, the reply says so. ## The Map The Map shows OpenAgents as one zoomable graph: the router every message reaches first, its routes, the prepared answers and knowledge behind them, the chat model, Coder, the coding agents, the plugins, and the screens an answer can open. Each kind has its own color, listed in the legend. Open it from **Map** in the sidebar's footer of [OpenAgents for Mac](/docs/mac), from **Commands** (Cmd+K, **Open the map**), or from the **Window** menu. Or ask in a Mac chat: "show me how you route things". - Drag to pan; pinch, or Cmd and the wheel, to zoom. - A click on a node shows its details; a double-click zooms in. - A ring shows health: no ring is measured and good, a red ring is measured and weak, and a dashed ring isn't measured yet. A red dot marks a gap, where OpenAgents is thin. - The **Gaps** panel lists them, and an outline lists every node. - Each plugin shows the step it has reached: Not packaged, Candidate, a verdict, Reproduced, Validated, or Adopted. The phone and the Terminal answer the same question with a sentence; the Map is on the Mac. Next: [Settings](/docs/settings). --- Source: https://openagents.com/docs/settings # Settings Coder's settings on a computer live in one file, `~/.openagents/settings.json`. The Mac app, OpenAgents Terminal, the `openagents` command, and the computer's host all read it. With no file, every setting is its default. ## Change a setting ```sh openagents settings show # every setting and the file openagents settings get coder.providers openagents settings disable devin # Coder won't use Devin CLI openagents settings enable devin # back on openagents settings set coder.start ask_first openagents settings unset coder.start # back to the default ``` Lists are comma-separated. A bad value changes nothing and says why. In OpenAgents Terminal, `/settings` shows them. In the Mac app, **Settings → Coder** changes `coder.start` and turns agents off and on (`coder.disabled`). Every coding agent signed in on the computer is on: nothing needs enabling. Settings only turn an agent off or change the order. ## The keys | Key | Values | Default | What it does | | --- | --- | --- | --- | | `coder.disabled` | any of `codex`, `claude`, `grok`, `devin`, `opencode` | none | The coding agents you turned off; Coder never uses them. Every other agent is used whenever it's signed in on this computer and has room. At least one stays on. See [Coding agents](/docs/coding-agents). | | `coder.providers` | up to 5 of `codex`, `claude`, `grok`, `devin`, `opencode`; each may add `:MODEL` | none: Codex, Claude Code, Grok Build, Devin CLI, OpenCode | The order Coder tries agents in, first preferred, and a model for any of them. Agents you leave out still follow in the default order. | | `coder.start` | `at_once`, `ask_first` | `at_once` | Whether a coding reply starts Coder at once, or only offers **Run Coder**. It decides for your phone's requests to this computer too. | | `coder.usage_threshold_percent` | 1 to 100, or `off` | `90` | How full an agent's usage window can read before Coder moves on to the next agent. With `off`, Coder moves on only when an agent turns it away. | | `coder.projects` | folders | none: any Git checkout | Which folders hold your projects. Coder runs only in a checkout inside one of them, and the Mac app tries them when a chat names no project. | | `coder.access` | `full`, `toolchains`, `boundary` | `full` | What Coder's commands may reach. `full`: your own access; Coder runs every step without asking. `toolchains`: writes only in Coder's worktree, with this computer's developer programs and the network. `boundary`: the plain sandbox. | Examples: ```sh openagents settings set coder.providers claude,codex # Claude Code first openagents settings set coder.providers codex,opencode:openrouter/MODEL openagents settings set coder.disabled grok,opencode # turn two off openagents settings set coder.projects ~/code,~/work openagents settings set coder.access toolchains ``` OpenCode runs on the model its own configuration names (its `model` setting), or the one you name as `opencode:PROVIDER/MODEL`. Devin CLI bills its own paid API for each run; turn it off if you don't want Coder to use it. The Mac app reads the file when Coder first starts a run; restart the app after editing the file by hand. A file that can't be read is never treated as the defaults: Coder refuses to run and names the file, and a coding reply only offers Coder until you fix or remove it. ## The Mac app's own settings **Settings** (Cmd+,) has these pages: | Page | What's there | | --- | --- | | Appearance | **Theme**: System (as the computer is set), which is the default, Light, or Dark. **Reduce motion**, which keeps the Verse's camera still. | | Text size | Smaller, default, larger, or largest (90, 100, 115, or 130 percent). | | Keyboard shortcuts | Every shortcut. They can't be changed yet. | | Notifications | **Notify me about Coder**: when Coder asks you something, finishes, or fails while OpenAgents isn't in front. | | Coder | Each coding agent's sign-in and usage, **Start at once** or **Ask first**, and **Agents Coder may run**, each on until you turn it off. | | Phones and computers | Connecting and removing phones, and Coder's project. | | Archived chats | Chats you archived, with **Restore**. | They're saved in the same file, under `app`. ## Environment variables | Variable | What it does | | --- | --- | | `OPENAGENTS_SETTINGS` | Use another settings file. | | `OPENAGENTS_CHAT_HOME` | Keep chats somewhere other than `~/.openagents/chat`. | | `OPENAGENTS_TASKS` | Keep Coder's tasks somewhere other than `~/.openagents/tasks`. | | `OPENAGENTS_CHANNEL`, `OPENAGENTS_VERSION` | For the installer: the `rc` or `stable` channel, or one version. | | `OPENAGENTS_NO_LAUNCH=1` | For the installer: don't open the Terminal afterward. | | `NO_COLOR` | OpenAgents Terminal draws with no color. | Next: [Troubleshooting](/docs/troubleshooting). --- Source: https://openagents.com/docs/pricing # Pricing Chatting with OpenAgents is free, and so is Coder on your own computer. See every plan side by side on [Pricing](/pricing). ## Free daily allowance When you're signed in, Coder's `auto` model is free up to about $1 of model use a day. When today's allowance is used up, Coder tells you and keeps going on your own keys or subscriptions, or on credit you add. The allowance starts again each day at midnight UTC. ## Pro Pro is for cloud environments: a repository set up, built, checked, and saved on our machines so your tasks can start from it. It isn't on sale yet. When it is, **Settings → Plan** shows how to subscribe. | | Pro | | --- | --- | | Price | $20 a month | | Hours | 100 machine-hours a month | | Machine | 2 vCPU, 8 GB | | At once | 2 machines | | Saved environments | 20 GB, up to 10 saved versions | | Run length | No limit from us; set your own if you want one | | Models | Your own Claude or Codex key or subscription | Unused hours don't roll over to the next month. ## Extra hours When the month's 100 hours run out, setups stop until the next month starts. To keep going, turn on **Extra hours** in **Settings → Plan** and set a monthly limit. Extra hours are $0.18 a machine-hour, paid from your credits, and never more than the limit you set. They're off until you turn them on. **Settings → Plan** shows the hours you've used this month, your saved storage, and your extra-hours limit. --- Source: https://openagents.com/docs/troubleshooting # Troubleshooting ## Coder isn't answering on this Mac The Mac app says "Coder isn't answering on this Mac" when its background helper (the host) doesn't answer. The app keeps trying on its own. 1. Click **Try again** in [OpenAgents for Mac](/docs/mac). 2. If the app says "OpenAgents needs your OK to run in the background", click **Open Login Items** and turn on OpenAgents under **Allow in the Background**, then come back. 3. If it says "Coder couldn't start on this Mac", or the message lasts, quit OpenAgents and open it again. 4. Still stuck? Report a problem (below) with what the screen says. ## `coder` isn't found after installing Open a new terminal: the installer added `~/.openagents/bin` to your `PATH`, and only new terminals see it. Or run it by its full path, `~/.openagents/bin/coder`. If you installed with `CODER_NO_PATH_UPDATE=1`, add this line to your shell's startup file: ```sh export PATH="$HOME/.openagents/bin:$PATH" ``` ## Coder has nobody to answer Coder needs at least one of these on the computer: Claude Code or Codex signed in (run `claude` or `codex` once and sign in), OpenCode installed, your openagents.com sign-in (`coder login`), or an OpenRouter key ([how](/docs/coder-plugins)). Then press `Shift+Tab` in Coder to see who can answer. ## "Today's free allowance on OpenAgents is used up" Coder's own loop on OpenAgents models is free up to a daily allowance. Until it resets, press `Shift+Tab` to answer with Claude Code or Codex on your own plan, or turn on OpenRouter BYOK and pick a model on your own key in `/models`. The allowance starts again at midnight UTC. ## My computer's chats don't show on the website 1. Run `coder login` on that computer and approve the code at [openagents.com/device](https://openagents.com/device). 2. In Coder, type `/sync on`. 3. Check [Settings](https://openagents.com/settings): the computer should be listed. A reply from the site reaches Coder only while Coder is open on that computer. See [Connect a computer](/docs/connect-a-computer). ## My phone won't connect - Check that the computer's host is running: `openagents connect status`. If nothing answers, start it with `openagents host serve --iroh --control` and leave it running. - Run `openagents connect invite` again and scan the new code in [OpenAgents for iPhone](/docs/iphone). Each code works once. - Can't scan? Run `openagents connect invite --text` and paste the code it prints in the phone's **Paste a code**. ## A coding agent says it isn't signed in Coder uses only agents signed in on the computer it runs on, as the same user. 1. Run the agent's own program in a terminal on that computer (for example `codex` or `claude`) and sign in. 2. Check the Mac app's sidebar or **Settings → Coder**, or OpenAgents Terminal's **Agents** row: it should say **Signed in**. 3. Nothing needs enabling: Coder uses every signed-in agent. Only one you turned off is skipped (**Agents Coder may run**, or `openagents settings enable AGENT`). If the agent you asked for isn't available, Coder runs another one and the start says why. See [Coding agents](/docs/coding-agents). ## Coder won't start - **Not a project.** Coder needs a Git checkout with at least one commit. In the Mac app, **Choose folder…**; in the Terminal, start in your project's folder. If you set `coder.projects`, the checkout must be inside one of those folders. - **No agent available.** No allowed agent is signed in with room right now. Sign one in, or turn another on. - **Settings file can't be read.** Fix or remove `~/.openagents/settings.json`; the message names the problem. - **From the phone:** on the Mac, check that it's online, a project is picked, and **Let my phone start Coder here** is on. With **Ask first**, tap **Run Coder** under the reply. - **Offered but not started.** With **Ask first**, press Enter on an empty line in the Terminal, or choose **Run Coder** in the app. ## The usage meters look out of date The Mac app's usage meters come from the last reading your computer took; it reads again in the background when a reading is due. - **Reading usage…** means no reading yet. Wait a little. - **The sign-in has expired** or **No sign-in to read**: sign in to that agent again. - **Usage can't be read right now**: the provider didn't answer; it tries again later. - Grok Build has no meter: it doesn't report usage. An out-of-date meter never stops Coder by itself. Coder moves on from an agent only on a fresh reading, or when the agent turns it away. ## "Couldn't reach OpenAgents; try again." Send the message again. If a very long chat asks you to start a new one, start a new chat. ## Remove a phone Click **Remove** next to the phone in the Mac app's **Phones and computers**, or run `openagents connect remove DEVICE`. ## Report a problem In the iPhone app, open **Account → Report a problem**, or long-press the tab bar on any screen so the report knows where you were. Pick a kind, say what happened and what you expected, and add a screenshot if you want; you see it first, and the Wallet and key screens never attach one. **My reports** lists what you sent. You can also open an issue on [GitHub](https://github.com/OpenAgentsInc/openagents/issues). Next: [Run your own OpenAgents](/docs/self-host). --- Source: https://openagents.com/docs/self-host # Run your own OpenAgents Everything that runs openagents.com is open source under the Apache 2.0 license, in [one repository](https://github.com/OpenAgentsInc/openagents). You can run your own copy with your own model keys: the website, the account service, the chat worker that writes the answers, and, if you want, your own relay. This guide hasn't yet been followed start to finish on a clean Linux machine. If a step fails, [open an issue](https://github.com/OpenAgentsInc/openagents/issues/new) with the step and what it printed. The full guide, with every option, is [docs/self-host.md](https://github.com/OpenAgentsInc/openagents/blob/main/docs/self-host.md). ## The parts | Part | What it does | Needed | | --- | --- | --- | | Website | Pages, chat, sign-in, Settings | Yes | | Account service | GitHub sign-in and accounts; sends the chat worker's model calls to your keys | For sign-in | | Chat worker | Answers each chat message with a model | Yes | | Relay | Carries encrypted messages between the website and the chat worker | No: by default yours meet on relay.openagents.com, which only passes them along | ## What you need - macOS or Linux, and Rust from [rustup.rs](https://rustup.rs). - On Debian or Ubuntu, the build packages: `sudo apt-get install -y build-essential pkg-config git curl openssl lsof` - An [OpenRouter API key](https://openrouter.ai/keys) for the answers. - A [GitHub OAuth App](https://github.com/settings/applications/new) for sign-in, with homepage `http://127.0.0.1:4301` and callback `http://127.0.0.1:4301/auth/github/callback`. ## Start it Get the code: ```sh git clone https://github.com/OpenAgentsInc/openagents.git cd openagents ``` Write your private files. Replace the three values in angle brackets: ```sh export OPENAGENTS_SECRETS="$HOME/.openagents-secrets" mkdir -p "$OPENAGENTS_SECRETS" && chmod 700 "$OPENAGENTS_SECRETS" umask 077 cat > "$OPENAGENTS_SECRETS/github-oauth-local.json" <", "client_secret": "", "token_encryption_key": "$(openssl rand -base64 32)"} EOF cat > "$OPENAGENTS_SECRETS/openagents-web-cloud-byo-keys.json" <' > "$OPENAGENTS_SECRETS/openrouter.env" ``` Build and start everything. The first build takes a while: ```sh scripts/dev/full-local.sh start ``` Then open [127.0.0.1:4301](http://127.0.0.1:4301) on the same machine and send a message. Click **Log in** to sign in with GitHub. Stop everything with `scripts/dev/full-local.sh stop`. To use Coder in the terminal with your copy, run `~/.openagents/full-local/bin/coder login`. ## Your own relay The relay needs Postgres. Build it and start it on port 8080: ```sh sudo apt-get install -y postgresql sudo -u postgres createuser --pwprompt nostr-relay sudo -u postgres createdb --owner=nostr-relay nostr-relay cargo build --release -p nostr-relay --bin nostr-relay DATABASE_URL='postgres://nostr-relay:@127.0.0.1:5432/nostr-relay' \ NOSTR_RELAY_PORT=8080 \ "${CARGO_TARGET_DIR:-target}/release/nostr-relay" ``` Then restart the rest on it: ```sh scripts/dev/full-local.sh stop FULL_LOCAL_RELAY=ws://127.0.0.1:8080 scripts/dev/full-local.sh start --no-build ``` ## What's not covered yet - Projects (Connect GitHub), Environments, and paid plans need more setup than this; the [full guide](https://github.com/OpenAgentsInc/openagents/blob/main/docs/self-host.md#what-this-setup-leaves-out) says what each one needs. - This setup serves one machine. A public server also needs HTTPS and a Google Cloud Storage bucket for chats; the [full guide](https://github.com/OpenAgentsInc/openagents/blob/main/docs/self-host.md#putting-it-on-a-public-server) lists what the code asks for. Next: [FAQ](/docs/faq). --- Source: https://openagents.com/docs/faq # FAQ ## What does it cost? Chatting with OpenAgents is free, and we don't count your messages. Coder runs on your own computer with the coding agents you already use there, such as Claude Code and Codex, and each one's own plan covers it. Coder's own loop on OpenAgents models is free up to a daily allowance when you're signed in. Pro, for cloud environments, will be $20 a month with 100 machine-hours; it isn't on sale yet. See [Pricing](/docs/pricing). ## Do I need a computer? Not to chat. You need your own computer to run Coder: a Mac, Linux, or Windows computer with Coder installed ([Download and install](/docs/download)). We don't offer a hosted computer yet. ## Do I need an account? Not for the apps or Coder: each device makes its own key the first time it runs. An account ([log in](https://openagents.com/login)) keeps your website chats, and with `coder login` and `/sync on` it shows Coder's chats from your computer. See [Sync, share, and export](/docs/coder-sync). ## Which model answers the chat? Google's Gemini 3.8 Flash, on Vertex AI or through OpenRouter or the Vercel AI Gateway, with GLM as a backup. Jev, a small decision model from TypeSafe, decides how we reply. Ask the chat "What model is this?" to hear which one is answering now. See [Privacy and security](/docs/privacy-and-security). ## Do you keep or train on my chats? In the web chat on openagents.com, we keep your chats on our servers so you can open them again; you can delete one from its … menu in the sidebar. In the Mac app, Terminal, and phone app, your chats are saved on your device, and our chat service doesn't store your message text. We may use your chats to train and improve our models; on a paid plan you can ask us to opt you out, and we set that up with you. See [Privacy and security](/docs/privacy-and-security). ## Can I pick the model Coder uses? Yes. In Coder, `Shift+Tab` chooses who answers (Auto, Claude Code, Codex, OpenCode, or another agent), and `/models` chooses the model. See [Choose who answers](/docs/coder-agents). ## Can I attach a photo or a file? In Coder, yes: paste a screenshot, drop in the path of an image or a PDF, or write `@path/to/file` in your message. Chats on the website and in the apps are text only for now. ## Do I need Tailscale? No. Your phone reaches your computer directly or through our relay. Tailscale is an optional extra route if you already use it. ## Does Coder change my files? In the `coder` terminal app, yes: a chat works in the folder you open it in, like any coding agent, and `/rewind` puts back the files a turn changed. Background agents, Solver, and chats run from scripts work in their own copy of your project instead. Commands that would throw away uncommitted work are refused everywhere. See [Safety](/docs/coder-safety). ## Do plugin authors get paid? Not today. Credit is XP and your name, and XP isn't money. Paying plugin authors when their plugins are used is something we've talked about, not something we've built. ## Is it open source? Yes. The apps, the chat service, Coder, and the protocols are at [github.com/OpenAgentsInc/openagents](https://github.com/OpenAgentsInc/openagents), under the Apache License 2.0. ## When is version 1.0 out? Coder 1.0 is in release candidates now; the [download page](/download) shows the latest. Stable releases come after testing, and Coder updates itself when they're out. ## How do I see what changed in a build? On the phone, **Account → Changelog** lists what each build brought, and **Account → About this device** shows the version and build. Next: [Glossary](/docs/glossary). --- Source: https://openagents.com/docs/glossary # Glossary The words these docs use, in plain terms. | Word | Meaning | | --- | --- | | **Adoption** | When a plugin becomes one of Coder's defaults, after a Better result, three confirming checks by different people, and a Better validation. An OpenAgents operator signs it; it's never automatic. | | **Auto** | Coder's default choice of who answers a chat: it picks among the agents that are on and signed in. `Shift+Tab` picks one yourself. | | **Better, No clear change, Worse** | The three verdicts of a plugin test: whether Coder did better with the plugin than without it. | | **Check** | Rerunning someone else's published result. It confirms the result when you get the same verdict and disputes it when you don't. | | **Chat** | Talking with OpenAgents. The same chat on the website, the Mac app, the iPhone app, and the Terminal. | | **Coder** | Our coding agent. It does coding work on your own computer, in your terminal (`coder`) or from the apps, with the coding agents you're signed in to there or its own loop. | | **Coding agent** | Claude Code, Codex, OpenCode, Devin CLI, Cursor, Grok Build, and others: the programs Coder runs to do the work. Also called engines. | | **Computer** | A Mac, Linux, or Windows computer where Coder can run, which your phone can connect to. | | **Deck** | A slide presentation the Mac app shows full screen. | | **Defaults** | The plugins Coder uses for everyone, once their test results hold up. | | **Device key** | The key your phone or computer makes the first time it runs. It signs your messages and holds access to your computers. | | **Grid** | The Verse's shared world, where players walk around live and the Gym stands. | | **Gym** | Where plugins are tested on Coder, with and without, and the results are published and checked. | | **Host** | The background helper on a computer that keeps your chats, runs Coder, and answers your phone. The Mac app runs it for you. | | **Jev** | A small, fast decision model from TypeSafe. It decides how we reply to each message, and estimates how much of Coder's work is done. It writes no reply text. | | **Knowledge** | Cited reference entries, such as a method or how a command is used. A plugin can carry it; our product notes are knowledge too. | | **Level** | Your trainer level, worked out from your XP. Level 2 at 100 XP, 3 at 283, 4 at 520. | | **Map** | The Mac app's graph of how OpenAgents routes a message. | | **Microcoder** | The engine Coder runs its turns through. It is part of Coder: it installs with Coder and comes inside the Mac app, with nothing separate to download. | | **Nostr** | The open protocol of signed records OpenAgents runs on. | | **npub, nsec** | A Nostr public key and secret key. Share an npub; never share an nsec. | | **Pairing** | Connecting your phone to a computer by scanning its QR code. | | **Plugin** | Anything you add to OpenAgents: skills, workflows, knowledge, Wasm, and the tests that show whether it helps. | | **Prepared answer** | A reviewed answer we show at once when it fully answers a question. | | **Project** | A Git checkout Coder works in. | | **Relay** | A server that carries Nostr records. Ours is `relay.openagents.com`; it sees chat messages only encrypted. | | **Result** | A published plugin test: what Coder passed with the plugin and without it, and the verdict. | | **Router** | The part of OpenAgents that reads each message first and decides what serves it: a prepared answer, our notes, the chat model, Coder, or a screen. | | **Skill** | Instructions the agent reads before a task. A plugin made in chat is a skill. | | **Test, test set** | A test is one task for Coder with checks on how it went. A test set is a plugin's tests. | | **Thread** | One conversation: one row in your chat list. | | **Trainer** | You, in the Gym. Your trainer card shows your level and XP. | | **Validation** | A second test set, written by someone else, that shows a plugin helps beyond its author's own tests. | | **Verse** | The shared world in the apps. The Grid is its first place. | | **Wallet** | The iPhone app's bitcoin wallet. | | **Wasm** | Small sandboxed code a plugin can carry to do one bounded job. A workflow runs it. | | **Workflow** | A typed, step-by-step program a plugin carries. | | **World key** | A separate key for the Verse and your XP, kept apart from your device key. | | **Worktree** | A separate copy of your project on its own branch. Background agents, Solver, and Coder tasks from the apps work in one, so your checkout stays as it was. | | **XP** | Credit for work other people used. It isn't money. | The full engineering glossary is on [GitHub](https://github.com/OpenAgentsInc/openagents/blob/main/docs/glossary.md). --- Source: https://openagents.com/docs/api/quickstart # Quickstart The OpenAgents API sends your request to a good model for the job and charges the provider's price plus a small, posted margin. It speaks [Open Responses](https://www.openresponses.org/) and the OpenAI Chat Completions API, so the SDKs you already use work by changing two lines. **Beta.** Our own apps run on this API today. Keys for everyone aren't open yet; the guides here show how it works when they are. | | | | --- | --- | | Base URL | `https://api.openagents.com/v1` | | Same API, one domain | `https://openagents.com/api/v1` | | Key | `Authorization: Bearer oak_...` | ## 1. Get a key Keys start with `oak_`. Keep yours out of source code; put it in an environment variable: ```sh export OPENAGENTS_API_KEY=oak_... ``` ## 2. Send a request ```sh curl https://api.openagents.com/v1/responses \ -H "Authorization: Bearer $OPENAGENTS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "openagents/chat", "input": "Say hello in five words."}' ``` `openagents/chat` lets us pick the model. Name one yourself, such as `google/gemini-3.8-flash`, when you want that model. ## 3. Use the OpenAI SDK Python: ```python import os from openai import OpenAI client = OpenAI( base_url="https://api.openagents.com/v1", api_key=os.environ["OPENAGENTS_API_KEY"], ) reply = client.responses.create(model="openagents/chat", input="Say hello.") print(reply.output_text) ``` JavaScript: ```js import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.openagents.com/v1", apiKey: process.env.OPENAGENTS_API_KEY, }); const reply = await client.chat.completions.create({ model: "openagents/chat", messages: [{ role: "user", content: "Say hello." }], }); console.log(reply.choices[0].message.content); ``` Add `stream: true` to either call to get the answer as it's written. ## From the command line ```sh openagents inference google/gemini-3.8-flash "Say hello in five words." openagents inference openagents/chat --input "Tell me a story." --stream openagents inference models ``` It reads your key from `OPENAGENTS_API_KEY`. With no key, `--pay x402 --max-msat N` pays for one request over Lightning ([Pay per request](/docs/api/pay-per-request)). ## Next - [Models and prices](/docs/api/models): every model and what it costs. - [Which model to use](/docs/api/decisions): pick by task, price, and speed. - [Errors](/docs/api/errors): what each error means and what to do. - The OpenAPI description of every route: `https://api.openagents.com/v1/openapi.json`. --- Source: https://openagents.com/docs/api/models # Models and prices **Beta.** Prices on this page are the ones the API charges. ## Prices Each price is per million tokens, in US dollars: the provider's list price, plus our 5%, equals what you pay. You're charged in sats from your balance. | Model | Provider | Input | Cached input | Output | | --- | --- | --- | --- | --- | | `google/gemini-2.5-flash-lite` | Google Vertex AI | $0.1 + $0.005 = **$0.105** | $0.01 + $0.0005 = **$0.0105** | $0.4 + $0.02 = **$0.42** | | `google/gemini-3.8-flash` | OpenRouter | $0.75 + $0.0375 = **$0.7875** | $0.075 + $0.00375 = **$0.07875** | $3.75 + $0.1875 = **$3.9375** | | `google/gemini-3.8-flash` | Vercel AI Gateway | $0.75 + $0.0375 = **$0.7875** | $0.075 + $0.00375 = **$0.07875** | $3.75 + $0.1875 = **$3.9375** | | `google/gemini-3.8-flash` | Google Vertex AI | $0.75 + $0.0375 = **$0.7875** | $0.075 + $0.00375 = **$0.07875** | $3.75 + $0.1875 = **$3.9375** | | `google/gemini-4-argon` | OpenRouter | $2 + $0.1 = **$2.1** | $0.1 + $0.005 = **$0.105** | $10 + $0.5 = **$10.5** | | `google/gemini-4-argon`, From 2026-12-01 | OpenRouter | $4.2 | $0.21 | $21 | | `google/gemini-4-argon` | Vercel AI Gateway | $2 + $0.1 = **$2.1** | $0.1 + $0.005 = **$0.105** | $10 + $0.5 = **$10.5** | | `google/gemini-4-argon`, From 2026-12-01 | Vercel AI Gateway | $4.2 | $0.21 | $21 | | `google/gemini-4-argon` | Google Vertex AI | $2 + $0.1 = **$2.1** | $0.1 + $0.005 = **$0.105** | $10 + $0.5 = **$10.5** | | `google/gemini-4-argon`, From 2026-12-01 | Google Vertex AI | $4.2 | $0.21 | $21 | | `openai/gpt-5.6-luna` | OpenAgents (Pro) | $0.2 + $0.01 = **$0.21** | $0.02 + $0.001 = **$0.021** | $1.2 + $0.06 = **$1.26** | | `openai/gpt-5.6-sol` | OpenAgents (Pro) | $4 + $0.2 = **$4.2** | $0.4 + $0.02 = **$0.42** | $20 + $1 = **$21** | | `openai/gpt-5.6-terra` | OpenAgents (Pro) | $2 + $0.1 = **$2.1** | $0.2 + $0.01 = **$0.21** | $12 + $0.6 = **$12.6** | | `zai/glm-5.3-flash` | OpenRouter | $0.15 + $0.0075 = **$0.1575** | $0.03 + $0.0015 = **$0.0315** | $0.5 + $0.025 = **$0.525** | | `zai/glm-5.3-flash` | Vercel AI Gateway | $0.15 + $0.0075 = **$0.1575** | $0.03 + $0.0015 = **$0.0315** | $0.5 + $0.025 = **$0.525** | | `zai/glm-5.3-flash` | Z.ai | $0.15 + $0.0075 = **$0.1575** | $0.03 + $0.0015 = **$0.0315** | $0.5 + $0.025 = **$0.525** | The same card is JSON at `GET /v1/rates`, open without a key. Each model in `GET /v1/models` carries its rows too. A few rules: - **The list price, whoever answers.** When a model has more than one provider, you pay that provider's row. Our own deals with providers never change the price you see. - **Promotions are their own rows**, labeled, beside the list price. - **Your own key costs nothing extra.** See [Bring your own key](/docs/api/bring-your-own-key). ## What each model can do | Model | Context | Most output | Tools | Images | JSON schema | | --- | --- | --- | --- | --- | --- | | `google/gemini-3.8-flash` | 1,048,576 | 65,536 | Yes | Yes | Yes | | `google/gemini-2.5-flash-lite` | 1,048,576 | 65,536 | Yes | Yes | Yes | | `google/gemini-4-argon` | 1,048,576 | 32,768 | Yes | Yes | Yes | | `zai/glm-5.3-flash` | 1,000,000 | 128,000 | Yes | No | No | | `openai/gpt-5.6-sol` | 400,000 | 128,000 | No | No | No | | `openai/gpt-5.6-terra` | 400,000 | 128,000 | No | No | No | | `openai/gpt-5.6-luna` | 400,000 | 128,000 | No | No | No | ## Tokens served **9,007,003 tokens served** (input and output). Counting since 2026-10-10 (UTC). | Caller | Free calls | Paid calls | | --- | ---: | ---: | | Our services | 536 | 0 | | Outside callers | 9,006,467 | 0 | Paid calls include **0 tokens on callers' own keys**. | Day (UTC) | Our services, free | Our services, paid | Outside callers, free | Outside callers, paid | Total | | --- | ---: | ---: | ---: | ---: | ---: | | 2026-10-14 | 0 | 0 | 758,812 | 0 | 758,812 | | 2026-10-13 | 0 | 0 | 2,062,058 | 0 | 2,062,058 | | 2026-10-12 | 0 | 0 | 3,630,343 | 0 | 3,630,343 | | 2026-10-11 | 0 | 0 | 2,555,254 | 0 | 2,555,254 | | 2026-10-10 | 536 | 0 | 0 | 0 | 536 | [Read the same counts as JSON](/api/v1/usage/tokens-served). Only answers with reported token counts are included. ## Model names Model names are `publisher/model`, such as `zai/glm-5.3-flash`. Names that start with `openagents/` pick a model for you by task: | Name | For | | --- | --- | | `openagents/auto` | We read the request and pick the task below | | `openagents/classify` | Labels, extraction, a short yes or no | | `openagents/fast` | Short replies, openers, summaries | | `openagents/chat` | General conversation | | `openagents/code` | Coding and tool use | | `openagents/long` | Inputs over 200,000 tokens | | `openagents/reason` | Hard multi-step problems | [Which model to use](/docs/api/decisions) helps you choose. --- Source: https://openagents.com/docs/api/decisions # Which model to use Start with a task name such as `openagents/chat` and change it only when you have a reason. Each one picks a model we've measured for that kind of work, and switches providers if one fails before answering. **Beta.** ## By task | If you need | Use | Why | | --- | --- | --- | | Labels, routing, a yes or no | `openagents/classify` | Cheapest and fastest; small models do short labels well | | A short, fast reply | `openagents/fast` | GLM-5.3 Flash: low price, quick first word | | General chat | `openagents/chat` | Balanced price and quality | | Coding with tools | `openagents/code`, or your own key | Picked by coding test scores | | Very long input | `openagents/long` | Models that read a million tokens | | Hard reasoning | `openagents/reason` | Larger models that think before answering | | Not sure | `openagents/auto` | We read the request and pick one of the above | ## Price, speed, or quality Every task name ranks models by quality first. To change the order, set `openagents.route.sort`: | You care most about | Set | What happens | | --- | --- | --- | | Quality | nothing | The best model for the task that meets its bar | | Price | `"sort": "price"` | The cheapest model that is good enough | | Speed | `"sort": "latency"` | The model that starts answering soonest | ```json { "model": "openagents/chat", "input": "Summarize this ticket.", "openagents": {"route": {"sort": "price"}} } ``` To cap what one request may cost, set `openagents.max_price` in dollars per million tokens: `{"input": "0.50", "output": "1.50"}`. A model priced above it is skipped. ## A specific model Name it, such as `google/gemini-3.8-flash`, when you need the same model on every request: for a test you compare over time, or a prompt tuned to one model. You still get the cheapest provider for it unless you set `route.order`. ## Your own key Use your own provider key with `"pay": "mine"` when you have your own contract, credit, or data terms with a provider. Your terms apply, and we charge nothing on top. See [Bring your own key](/docs/api/bring-your-own-key). ## Community providers People running open models on their own machines through Pylon will be able to serve API requests at prices they set, paid in bitcoin. That comes after the beta. ## Long conversations The API keeps nothing between requests: send the whole conversation each time. For very long histories, use `openagents/long`, or summarize older turns yourself. --- Source: https://openagents.com/docs/api/responses # Open Responses `POST /v1/responses` is our main API. It follows the [Open Responses specification](https://www.openresponses.org/specification) (version 2026-04-24), the open form of OpenAI's Responses API. **Beta.** ## Request ```json { "model": "openagents/chat", "instructions": "Answer in one sentence.", "input": [ {"type": "message", "role": "user", "content": "What is Lightning?"} ], "stream": false, "max_output_tokens": 500 } ``` | Field | What it does | | --- | --- | | `model` | A model name or a task name ([Models](/docs/api/models)) | | `input` | A string, or a list of items: messages, function calls, and their outputs | | `instructions` | The system prompt | | `tools`, `tool_choice` | Function tools; `tool_choice` is `auto`, `required`, `none`, one named function, or `allowed_tools` | | `text.format` | `text`, `json_object`, or `json_schema` for structured output | | `reasoning.effort` | How hard a reasoning model thinks | | `temperature`, `top_p` | Sampling, where the model supports it | | `max_output_tokens` | The longest answer | | `stream` | `true` for server-sent events | | `openagents` | Our options: [routing](/docs/api/routing), privacy, and who pays | The API keeps nothing between requests. `store: true` and `previous_response_id` answer `400`; send the whole conversation each time. ## Response ```json { "id": "resp_...", "object": "response", "status": "completed", "model": "google/gemini-3.8-flash", "output": [ {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Lightning is ..."}]} ], "usage": {"input_tokens": 24, "output_tokens": 18, "total_tokens": 42}, "openagents": { "model": "google/gemini-3.8-flash", "upstream": "vertex", "attempts": [{"upstream": "vertex", "outcome": "ok", "ms": 840}], "cost": {"upstream_usd": "0.0000855", "margin_usd": "0.0000043", "price_usd": "0.0000898", "price_sats": 0} } } ``` `openagents` says which model and provider answered, every provider tried, and what the request cost: the provider's price, our margin, and the sum, in dollars and sats. Amounts are decimal strings, so no rounding sneaks in. Every answer also carries these headers: ```text x-request-id x-openagents-model x-openagents-upstream x-openagents-cost-usd (answers without a stream) ``` ## Output items | Item | Holds | | --- | --- | | `message` | The answer: `output_text` and `refusal` parts | | `function_call` | A call to one of your tools: `name`, `call_id`, `arguments` | | `reasoning` | A reasoning model's summary, when the model gives one | To answer a tool call, send the conversation back with a `function_call_output` item carrying the same `call_id`. ## Streaming With `stream: true` the answer arrives as server-sent events, in this order, and ends with `data: [DONE]`: ```text response.created response.in_progress response.output_item.added response.content_part.added response.output_text.delta (many) response.output_text.done response.content_part.done response.output_item.done openagents:cost response.completed ``` Two events are ours: `openagents:route` (which model and provider took the request, before the first output) and `openagents:cost` (the cost, before the last event). Clients that don't know them can skip them, as the specification asks. If something breaks after the answer has started, the stream ends with `response.failed`. Errors are on their own page: [Errors](/docs/api/errors). --- Source: https://openagents.com/docs/api/chat-completions # Chat Completions `POST /v1/chat/completions` is the OpenAI Chat Completions API. Use it when your code or SDK already speaks it. It reaches the same models, the same way, at the same prices as [Open Responses](/docs/api/responses). **Beta.** ```sh curl https://api.openagents.com/v1/chat/completions \ -H "Authorization: Bearer $OPENAGENTS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "openagents/fast", "messages": [{"role": "user", "content": "Hi"}]}' ``` ## What works the same | Chat Completions | Notes | | --- | --- | | `system`, `developer`, `user`, `assistant`, `tool` messages | As in OpenAI's API | | Text and `image_url` parts | | | `tools`, `tool_choice`, `parallel_tool_calls` | Function tools | | `response_format` | `json_object` and `json_schema` | | `max_tokens`, `max_completion_tokens` | `max_completion_tokens` wins when both are set | | `reasoning_effort` | | | `temperature`, `top_p`, `stop`, `seed`, `user` | Where the model supports them; otherwise ignored | | `stream`, `stream_options.include_usage` | Usage arrives in the last chunk before `[DONE]` | | `finish_reason` | `stop`, `tool_calls`, `length`, `content_filter`, or `error` | | `usage` | Prompt, completion, cached, and reasoning tokens, plus our `openagents` cost object | | `openagents` | The same [routing options](/docs/api/routing) | ## What doesn't carry over | Feature | What happens | | --- | --- | | `n` above 1 | `400`; send separate requests | | `input_audio` parts, uploaded `file_id`s | `400`, naming the part | | A message's `name` | Dropped | | Reasoning | A summary arrives in a `reasoning` field; hidden reasoning can't be carried to the next turn | | Citations and annotations | Dropped | | Built-in tools such as web search | Function tools only | | Several output items in one turn | Joined into one message, in order | When you need reasoning across turns or more than one output item, use [Open Responses](/docs/api/responses). --- Source: https://openagents.com/docs/api/routing # Routing and credits Every request names a model or a task. We turn that into at most three tries, best first, and answer with the first one that starts writing. **Beta.** ## How we pick 1. **Who can serve it.** A model name means every provider that offers that model. A task name, such as `openagents/chat`, means its list of models. 2. **Who can't.** We drop a provider that can't do what your request needs (tools, structured output, images, its length), doesn't meet your privacy setting, costs more than your `max_price`, or is failing right now. 3. **Good enough.** For task names, a model must pass that task's quality bar, measured daily. 4. **Order.** Then by our prepaid credit first, then price, then how fast it starts answering. Your price is the same whichever one answers. 5. **Try.** If a provider fails before the first word, we try the next one. After the first word, a failure ends the answer with `response.failed`. The answer's `openagents` object lists each try. ## Your options All are optional, in an `openagents` object in the request body: ```json { "model": "openagents/chat", "input": "Hi", "openagents": { "route": {"sort": "price", "ignore": ["openrouter"]}, "privacy": "strict", "pay": "ours", "max_price": {"input": "0.50", "output": "1.50"}, "fallbacks": ["zai/glm-5.3-flash"] } } ``` | Option | What it does | | --- | --- | | `route.sort` | `quality` (the default), `price`, or `latency` | | `route.order` | Providers to try first, in order | | `route.only` | Use only these providers | | `route.ignore` | Never use these providers | | `privacy` | `strict` (the default) or `standard`; see [Privacy](/docs/api/privacy) | | `pay` | `ours` (the default) or `mine` for [your own key](/docs/api/bring-your-own-key) | | `max_price` | The most you'll pay, dollars per million tokens, margin included | | `fallbacks` | Other models to try if yours can't answer | Providers are named by their short ids: `vertex` (Google Vertex AI), `zai` (Z.ai), `pro` (OpenAgents Pro), `openrouter`, and `vercel` (Vercel AI Gateway). `GET /v1/models` lists which serve each model. ## Our credit and your price We hold prepaid credit with some providers and spend it first, but only on models that pass the task's quality bar. Credit lowers our cost, never your price: you always pay the list price plus our margin on the [rate card](/docs/api/models). --- Source: https://openagents.com/docs/api/bring-your-own-key # Bring your own key You can use your own provider key through the API. Requests on your key go to your provider account, on your terms, and we charge nothing for them. **Beta.** ## Use it Add `"pay": "mine"` to the `openagents` object: ```json { "model": "google/gemini-3.8-flash", "input": "Hi", "openagents": {"pay": "mine"} } ``` With `"pay": "mine"`, only your own keys are used. If none of them can serve the request, you get an error; we never fall back to our accounts and charge you. ## What it costs | | | | --- | --- | | Our fee | None during the beta | | Your provider's charge | Billed to you by your provider | | Usage | Still counted, so it shows with the rest of your usage | ## Your key's safety Your key is stored sealed, used only for your own requests, and never shown back in full. You can remove it at any time. ## When to use it - You already have credit or a contract with a provider. - You need a provider's own data terms to apply. - You want a model we don't offer yet, through a provider you use. --- Source: https://openagents.com/docs/api/pay-per-request # Pay per request You can call the API with no account and no key: pay for each request in bitcoin over Lightning. This uses [x402](https://github.com/x402-foundation/x402), an open standard for paying for HTTP requests. **Beta.** Paying per request is off on this API right now; use an API key. ## How it works 1. Send the request with no `Authorization` header. 2. The answer is `402 Payment Required`. Its body says the price, and its `PAYMENT-REQUIRED` header holds a Lightning invoice for exactly that request. 3. Pay the invoice with any Lightning wallet. The wallet gives you a proof of payment (the preimage). 4. Send the same request again, byte for byte, with the proof in a `PAYMENT-SIGNATURE` header. You get the answer, with a `PAYMENT-RESPONSE` header saying the payment was accepted. ```sh curl -i https://api.openagents.com/v1/responses \ -H "Content-Type: application/json" \ -d '{"model": "google/gemini-3.8-flash", "input": "Say hello.", "max_output_tokens": 200}' ``` ```http HTTP/1.1 402 Payment Required PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi... {"error": {"type": "payment_required", "message": "This request costs up to 3 sats ($0.0021). ..."}, "price_sats": 3, "price_usd": "0.0021", "x402Version": 2} ``` The `PAYMENT-REQUIRED` header is base64 JSON. Its `accepts[0]` is the payment terms; `accepts[0].extra.invoice` is the invoice. To send the proof, base64-encode `{"x402Version": 2, "accepted": , "payload": {"preimage": ""}}` as the `PAYMENT-SIGNATURE` header. ## With the `Payment` scheme (MPP) When the API takes it, the same `402` also carries a `WWW-Authenticate: Payment` challenge (method `lightning`, intent `charge`) for the **same invoice**. Clients that speak the `Payment` scheme, such as `lnget` and `mppx`, pay it and send the same request again with `Authorization: Payment `: the challenge echoed back and `payload.preimage`, as base64url JSON. The answer carries a `Payment-Receipt` header. One invoice pays once. After it pays one request, the same preimage is refused whichever header carries it. ## From the command line The `openagents` command pays from your OpenAgents wallet and does all four steps: ```sh openagents inference google/gemini-3.8-flash "Say hello." --pay x402 --max-msat 10000 ``` `--max-msat` is the most you will pay, in millisatoshis (10000 is 10 sats). It refuses an invoice above it. ## What you pay - **The most the request could cost.** We price the request before it runs: the model's price from the [rate card](/docs/api/models), plus our margin, for the most input your request can hold and the most output it allows. Set `max_output_tokens` to lower the price. - **Whole sats, rounded up**, at the bitcoin price the rate card shows. - **No refund of the unused part.** The answer's actual cost is in its `x-openagents-cost-usd` header, but the payment covers the request as quoted. To pay only what each answer costs, use a key with credit instead. - **No answer, no charge.** If every provider fails before answering, or no provider can take the request, send the same request with the same `PAYMENT-SIGNATURE` again: the payment still counts. - **One payment, one answer.** A proof is used once, and only for the request it was issued for. A different body needs a new invoice. ## What needs a key A paid request covers one model turn and keeps nothing. Stored responses (`store`, `previous_response_id`), hosted tools such as web search, and the WebSocket need an API key. ## The API's description Every route is described in OpenAPI 3.1 at `https://api.openagents.com/v1/openapi.json`. --- Source: https://openagents.com/docs/api/for-agents # For agents How an agent finds OpenAgents, says who it is, and pays. Every step is one request or one command. **Beta.** ## Find us Start from any of these. None needs a key. | What | Where | | --- | --- | | A short index of the site and its docs | `https://openagents.com/llms.txt` | | Every doc in one file | `https://openagents.com/llms-full.txt` | | The API, described in OpenAPI 3.1 | `https://api.openagents.com/v1/openapi.json` | | The API catalog | `https://openagents.com/.well-known/api-catalog` | | The AI catalog (MCP, agent card, skills, API) | `https://openagents.com/.well-known/ai-catalog.json` | | The docs as an MCP server | `https://openagents.com/mcp/docs` | | How keys work | `https://openagents.com/auth.md` | | Models and prices as JSON | `https://api.openagents.com/v1/rates` | Any page is also Markdown: add `.md` to its address, or send `Accept: text/markdown`. ```sh curl -s https://openagents.com/llms.txt ``` ## Say who you are You don't have to. A call paid per request needs no account. When you do want one: | How | What to send | Status | | --- | --- | --- | | An API key | `Authorization: Bearer oak_...`. A person makes it at [Settings, API keys](https://openagents.com/settings/api-keys). | Works now | | Sign in for a person (OAuth) | For MCP clients and agents acting for someone: [Sign in with OAuth](https://openagents.com/auth.md#sign-in-with-oauth) | Works now: the token opens [openagents.com/mcp](https://openagents.com/mcp) | | Your Nostr key | A signed `Authorization: Nostr ...` header (NIP-98) | Coming | ```sh curl https://api.openagents.com/v1/responses \ -H "Authorization: Bearer $OPENAGENTS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "openagents/chat", "input": "Say hello."}' ``` ## Pay ### With a key Calls on a key are paid from its credit, at each answer's actual cost. When the credit runs out the answer is `402` with the type `insufficient_balance`. Add credit at [Settings](https://openagents.com/settings), then retry. ### Per request, with no key Send the call with no `Authorization` header. The answer is `402 Payment Required` with the price and one Lightning invoice for exactly that request, written once for each way to pay listed below. Pay it once, then send the same request again with the proof in the header your method uses. Each step is in [Pay per request](/docs/api/pay-per-request). Paying per request is off on this API right now; use an API key. The `openagents` command does all of it from your wallet: ```sh openagents inference google/gemini-3.8-flash "Say hello." --pay x402 --max-msat 10000 ``` ### Ways to pay | Method | Challenge | You send | You get back | Status | | --- | --- | --- | --- | --- | | A key with credit, bought by card | `401` without one | `Authorization: Bearer oak_...` | the answer | Works now | | [x402](https://www.x402.org/) on Lightning (`PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`) | | | | Coming | | The `Payment` scheme on Lightning, as used by [MPP](https://mpp.dev/) (`WWW-Authenticate: Payment`) | | | | Coming | | [L402](https://docs.lightning.engineering/the-lightning-network/l402) (`WWW-Authenticate: L402`) | | | | Coming | | Dollar stablecoins on Bitcoin ([Taproot Assets](https://github.com/OpenAgentsInc/tap-ldk)) over Lightning | | | | Coming | | Agent checkout for credits and Pro: [ACP](https://www.agenticcommerce.dev/), [UCP](https://ucp.dev/), [AP2](https://ap2-protocol.org/) | | | | Coming | This table is read from the API itself, so it lists a way to pay only while the API takes it. The `402` answer lists the same ways (its `methods` field), and so do the OpenAPI description (`x-payment-info` on each paid route), the [API catalog](/.well-known/api-catalog), and the docs MCP server's `list_payment_methods` tool. Follow the plan in [#11085](https://github.com/OpenAgentsInc/openagents/issues/11085). ## What you get back A paid answer carries a receipt header from the method you used (`PAYMENT-RESPONSE` for x402, `Payment-Receipt` for the `Payment` scheme), our own receipt id in `x-openagents-receipt`, and the answer's actual cost in `x-openagents-cost-usd`. Errors are listed in [Errors](/docs/api/errors). --- Source: https://openagents.com/docs/api/errors # Errors An error comes back as JSON with an HTTP status: ```json { "error": { "type": "invalid_request", "code": "invalid_request", "param": "input", "message": "The request body isn't a valid request: ..." } } ``` **Beta.** | Status | `type` | What it means | What to do | | --- | --- | --- | --- | | 400 | `invalid_request` | The request is malformed, or asks for something the API doesn't do (such as `store: true`) | Fix the field named in `param` | | 401 | `unauthorized` | The key is missing, wrong, or revoked | Check the `Authorization` header | | 402 | `insufficient_balance` | Your balance can't cover the request | Top up, then retry | | 402 | `payment_required` | You sent no key, so the request must be paid for | Pay the invoice in `PAYMENT-REQUIRED` and send the request again ([Pay per request](/docs/api/pay-per-request)), or use a key | | 403 | `limit_reached` | A limit you set was hit; `param` names it | Raise the limit, or wait for it to reset | | 404 | `not_found` | No such model or route | Check the model name against `GET /v1/models` | | 429 | `too_many_requests` | Too many requests at once | Retry after a short wait | | 500 | `server_error`, `model_error` | Something broke on our side or the model's | Retry; tell us if it keeps happening | | 502 | `upstream_failed` | Every provider we tried failed before answering | Retry, or name another model | | 503 | `no_route` | No provider meets your request's needs, privacy setting, or price cap | Loosen `route`, `privacy`, or `max_price` | Every answer has an `x-request-id` header. Include it when you ask us about a request. ## Errors mid-answer Once an answer has started, an error can't change the status code. A stream ends with a `response.failed` event, and a full answer comes back with `"status": "failed"`. Either way the `error` object carries a `code` and a `message`. --- Source: https://openagents.com/docs/api/limits # Limits you set We don't cap how much you use the API. You can set your own limits on your account and on each key, and we hold every request to them. **Beta.** | Limit | What it stops | | --- | --- | | Spending cap | Spending more than an amount per day, week, or month | | Price per request | Any model priced above your cap, per million tokens | | Allowed models | Models you haven't allowed | | Allowed providers | Providers you haven't allowed | | Rate cap | More than a number of requests per minute | | Expiry | Any use of the key after a date | A request that hits one of your limits gets `403 limit_reached`, with `param` naming the limit. Nothing else is charged for it. For a single request, `openagents.max_price` caps its price without changing your key's settings; see [Routing](/docs/api/routing). --- Source: https://openagents.com/docs/api/privacy # Privacy and data use **Beta.** ## What we keep We keep counts and timings for each request: which model and provider answered, how many tokens, how long it took, and what it cost. We don't keep your prompts or the answers. ## Where your request goes You choose with `openagents.privacy`: | Setting | Your request goes only to providers that | | --- | --- | | `strict` (the default) | Don't train on it and don't keep it | | `standard` | Don't train on it, but may keep it for a short time to check for abuse | Each provider in `GET /v1/models` says whether it keeps nothing (`zero_retention`). A provider whose terms we haven't checked never gets `strict` requests. Today that's Z.ai and OpenAgents Pro, which serve `standard` requests only. ## Your own key With `"pay": "mine"`, your request goes to your own provider account, under your own terms with that provider. See [Bring your own key](/docs/api/bring-your-own-key). ## More The [Privacy Policy](/privacy) covers everything else about your data at OpenAgents.