openai package, so there is no new SDK to learn.
In about ten minutes you’ll have a research agent of your own that looks things up and cites its sources, give it a sandbox to work in, and then hand the controls to your coding agent and your own code.
Credit at sign-up is paused while we tighten our sign-up checks, so a new account starts with no credit. The agent on this page uses GPT-5.6 Luna on Orca credit, which the Free plan does not include. To run it, any one of these works:
- Buy credit.
- Add your own OpenRouter key, and use
openrouter/openai/gpt-5.6-lunaas the model. - Ask us for some credit on Discord: discord.gg/btTYzdzvqq.
Why Orca
The OpenAI Agents API, hosted
Point the official
openai package at Orca and keep your code standard. No new SDK.A sandbox for every session
A session can have its own sandbox to run commands and write files. Idle sandboxes go to sleep with their files kept.
Any model, and you choose who pays
Any model on OpenRouter on your Orca credit, or your own provider key. The model name says which, and Orca never switches it.
Web search in one line
Add the
web_search tool and the agent looks things up on its own, paid like its model calls.Agents ready to copy
A kit carries an agent with its skills and templates. Orca publishes kits, and anyone can copy one into their own account, as you’re about to.
Your coding agent at the controls
The
orca CLI’s MCP server lets Claude Code, Codex, or Cursor create and run agents for you.What you’ll do
- Install the CLI and sign in.
- Get your first agent: copy it with one command, or build it from a few lines of code.
- Ask it something, then have a conversation.
- Give it a sandbox to run code and save files in.
- Let your coding agent drive.
- Run it from your own code.
- See what it cost, and clean up.
Or hand this page to your coding agent
If you work in Claude Code, Codex, or Cursor, it can do the typing while you watch. Paste this prompt:1. Install the CLI and sign in
orca binary to ~/.local/bin. If your shell then says orca: command not found, add that folder to your PATH as the script suggests, and open a new terminal. On Windows, download the binary from the releases page. Copying a kit needs CLI 1.4.0 or later: an older CLI updates itself with orca update.
balance is your Orca credit. A new account starts at 0 on the Free plan: add credit before step 3, or use your own provider key.
2. Get your first agent
Your first agent is Scout, a research assistant that searches the web and answers with its sources. This is all of it:orca/openrouter/<id> runs on your Orca credit; <provider>/<id>, such as anthropic/claude-sonnet-4-5, runs on your own key for that provider. See models and provider keys.
Get Scout into your account whichever way you like:
- Copy it (one command)
- Build it from code
Scout is shared as a kit, a link anyone can copy an agent from.It shows the same definition as the code above.
1
Copy it into your account
orca kits show https://app.orcapods.ai/kits/kit-tdCEUXGA3NbuIWJJ6 prints what the kit holds before you copy it: Scout’s instructions and tools in full, and what it runs, reaches, and spends. orca kits copy prints the same, then asks y/N before it copies anything.2
See your agent
3. Ask it something
Ask Scout something it has to look up:orca chat scout with no question. You’re now chatting with Scout, and it remembers what you said. Try a question, then a follow-up:
session session_...: a session is one conversation, and Orca keeps it. orca chat scout --session session_... (with your session’s ID) picks it up again tomorrow, and the Sessions page in the dashboard shows every turn.
4. Give it a sandbox
Add--sandbox, and the conversation runs in a sandbox, a private machine of its own where Scout can run code and save files. Anything it saves in /workspace/outputs is kept for you to download:
session session_.... Use that ID in place of session_... to download the file here, then delete the session to shut the sandbox down:
--all saves every file from Scout’s last turn here, so you now have python-releases.csv. To keep working in the same sandbox first, with the files where Scout left them, run orca chat scout --session session_... before you delete it. A sandbox that sits idle goes to sleep and stops using machine time, with its files kept for when the session needs it again.
To hand Scout a file of yours, add --file data.csv to orca chat: it lands in the sandbox at /workspace/data.csv.
5. Let your coding agent drive
Give your coding agent Orca’s tools, and you can run your agents just by asking.orca mcp serve is an MCP server with one tool per CLI action, so your coding agent can copy kits, create agents, chat with them, and read your usage and wallet. It uses the login you already have.
- Claude Code
- Cursor
- Codex
Install the Orca plugin. It registers the MCP server and adds a skill that knows the CLI:Or add only the MCP server:
- “Ask Scout to research the trade-offs between SQLite and Postgres for a small app, and summarize its answer.”
- “Make a copy of Scout called reviewer that reviews pull request descriptions instead, and run it on this branch’s last commit message.”
- “Continue my last session with Scout and ask it for a shorter answer.”
- “How much Orca credit do I have left, and what did I spend today?”
6. Run it from your own code
Everything so far went through the CLI, which calls the same API your application will. Your code uses the officialopenai package with an Orca API key. If you built Scout from code in step 2, you already have the package: skip to the key.
Install the openai package. It needs Python 3.10 or later, or Node 22.18 or later. Check your version first, and update it if it’s older:
ORCA_API_KEY without printing it. A new terminal won’t have it, so run this again there.
7. See what it cost, and clean up
Every call is recorded with what it cost, down to the session:orca sessions get session_... shows one session’s cost, tokens, and machine time.
- Model tokens and web searches on an Orca credit model are paid from your credit. On your own provider key, that provider bills you.
- Sessions without a sandbox use no machine time. On this page, only step 4 used any.
- Sandboxes use machine time from your plan. On Pro and Max they need your plan’s minimum balance; on Free, the included time runs at any balance, and time past it needs the minimum. Delete a sandbox session when you are done with it.
start-here with orca keys revoke <its id> --yes, and close the terminal: its ORCA_API_KEY still holds the revoked key.
Where to go next
Build your own agent
Every call explained, from creating an agent to streaming its answers.
Agent recipes
Complete agents to copy: a support agent, a data analyst, a code reviewer, and more.
Subagents
Let one agent split a task and hand the pieces to helpers.
Ready-made agents
Copy Scout or Cram Coach, each with a page that takes you from nothing to using it every way.
How kits work
What a kit holds, and how to read one before you copy it.