Start here

This is the route we walk with every design partner. Five short sections, each ending with something real: an agent you built, an endpoint your product calls, the harness running in your own terminal, and numbers to compare it against. Every command below is copy-paste. They match orca CLI 0.6.0 and orcacode 0.2.0, the releases the installers ship today.

1 and 2. Sign in, build an agent

Get a workspace, sign the CLI in, and create your first agent from a YAML file on the Orca Harness runtime.

3. Publish and use it

Put the agent behind an endpoint with its own key, and call it from curl, the CLI or an SDK.

4 and 5. Orcacode, then compare

Run the same harness locally on your repo, then run one prompt on two harnesses and read the numbers.

Get a workspace

No account yet? Sign up at app.orcapods.ai/sign-up and create an organization. That organization is your workspace, and it starts with free credits and no card. Already have one? Sign in at app.orcapods.ai.

Sign the CLI in

curl -fsSL https://orcapods.ai/install.sh | sh
orca login
orca whoami

orca login opens the dashboard to authorise the CLI and stores a tenant key in ~/.config/orca/config.json. On a machine with no browser it prints a one-time code to approve on any device. Other flows, including CI, are under Authentication.

Meet the agent that is already there

orca agents list

One agent is listed before you have created anything: Sonar, which answers questions about Orca from this documentation. It is there whenever you get stuck, in the dashboard under Agents or from the terminal:

orca run sonar "How do I attach an MCP server to an agent?"

2. Your first agent, on the harness

Agents are created from a YAML document. Copy this block and paste it into your terminal: the document is piped into the CLI, which creates the agent in one go. It is written to paste cleanly into bash, zsh and fish. The runtime is marlin, which is Orca Harness running in a per-session sandbox: the same kernel you will run on your own machine as Orcacode in section 4. Marlin always runs isolated, so workerMode: sandbox is required, and its model ids are namespaced.

echo 'name: support-triage
runtime: marlin
model: anthropic:claude-sonnet-4-6
systemPrompt: |
  You triage support tickets. For each ticket return three lines:
  Category: one of billing, access, bug, feature, other
  Priority: urgent, normal or low
  Reply: the first reply to send the customer, two sentences at most
tools: ["@default"]
workerMode: sandbox' | orca agents create -f -

To keep the document for later edits, save the YAML as support-triage.yaml and run orca agents create -f support-triage.yaml instead; orca agents update -f takes the same file.

orca run support-triage "Ticket #4412: I was charged twice this month and want a refund."

The run streams live in the terminal: the model’s text, each tool call, and a Tokens line at the end. Add --json for one JSON object per event, or --detach to start it and read it back later:

orca run support-triage "Ticket #4413: the export button does nothing in Safari." --detach
orca runs get

--detach prints the run id and returns immediately. orca runs get with no id opens a picker over your recent runs; pass an id to skip it. The same agent is now under Agents in the dashboard, with its sessions and a task box. Every field in the file is explained under Agent documents; what the agent may use next, skills, MCP servers, connected apps and memory, is one line each in that file or one click in the dashboard.

3. Publish it and use it

Publishing puts the agent behind a stable HTTPS endpoint with its own keys, separate from your tenant key. Your product calls it; Orca runs it.

Publish and mint a key

orca agents publish support-triage --slug support --json
orca agents keys create support-triage --label my-app

The first command prints the published record. Its publicUrl is the endpoint your app calls, and it is built from two things: your organization id and the slug.

https://chat.orcapods.ai/v1/chat/org_.../support
                                 ↑       ↑
                                 org id  slug

The second command prints the chat key once, next to a key_... id. The key is the secret and travels in the Authorization header. The key_... id is only the handle you use to revoke that key later; it never appears in a URL.You do not have to copy the organization id by hand. This fetches it and builds the endpoint for you:

export PUBLIC_URL="https://chat.orcapods.ai/v1/chat/$(orca whoami --json | jq -r .tenantId)/support"
export CHAT_KEY="ao_production_..."   # the key printed above, not the key_... id
echo $PUBLIC_URL

set -x PUBLIC_URL "https://chat.orcapods.ai/v1/chat/"(orca whoami --json | jq -r .tenantId)"/support"
set -x CHAT_KEY "ao_production_..."   # the key printed above, not the key_... id
echo $PUBLIC_URL

Call it from your product

curl -N -X POST "$PUBLIC_URL/stream" \
  -H "Authorization: Bearer $CHAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Ticket #4414: I cannot sign in since the password reset."}'

The response is a Server-Sent Events stream: delta frames as the reply is written, tool frames if you published with --expose-tool-events, then one done. Conversations, polling instead of streaming, and per-agent spend caps are in the Publishing guide and the Chat Gateway API.

Or from the CLI and the SDKs

orca chat support "Ticket #4414: I cannot sign in since the password reset." --key "$CHAT_KEY"

Pick the one for your stack, not both:

npm install @orcapods/sdk

pip install orcapods

The SDKs wrap the control plane (create agents, start runs, stream events) with an ao_ tenant key from Library, API keys. Start at the SDK overview.

You have an endpoint. Put the agent on a schedule with Automations, share it as a kit from Shared templates, and watch spend on the Usage page (Credits and billing).

4. Orcacode, in your terminal

The marlin runtime your agent runs on is Orca Harness. Orcacode is the same harness as a local coding agent: one 6.7 MB binary, your repository, your model and keys, nothing hosted.

curl -fsSL https://orcapods.ai/orcacode.sh | sh
cd your-repo
orcacode --plan

Plan mode reads and proposes without touching files. Drop the flag for the normal mode, where shell, write and edit calls ask before running. It also runs unattended; this is a real run in a two-file project, output as printed:

orcacode --bare --no-session -p "List the files here and say in one sentence what this project is."

• list_dir
  2 entries
• read_file README.md
• read_file calc.py
Files: `README.md`, `calc.py`: this is a tiny Python project with an addition function.
tokens: 1586 in, 101 out

The field manual takes it from here in the same order, a prompt, your workflow, your product: orcapods.ai/orcacode/docs. Providers, approvals, sessions, skills, MCP, hooks, plugins and the Rust SDK are all in there.

5. Compare it with another harness

Every runtime on Orca takes the same agent document, so the comparison is one document and one prompt. Paste this to create the same agent on the pi runtime (the Pi coding agent SDK), same model, same instructions:

echo 'name: support-triage-pi
runtime: pi
model: anthropic:claude-sonnet-4-6
systemPrompt: |
  You triage support tickets. For each ticket return three lines:
  Category: one of billing, access, bug, feature, other
  Priority: urgent, normal or low
  Reply: the first reply to send the customer, two sentences at most
tools: ["@default"]' | orca agents create -f -

Run the same ticket through both, then read them back:

orca run support-triage "Ticket #4415: our whole team lost access after the SSO change this morning." --detach
orca run support-triage-pi "Ticket #4415: our whole team lost access after the SSO change this morning." --detach

orca runs list --json | jq -r '.[0:2][].id' | xargs -n1 orca runs get

That reads back just the two runs you started, each with its own status, duration and Tokens line. For the two side by side, with the token lanes broken out:

orca runs list --json | jq -r '.[0:2][].id' | xargs -n1 orca runs get --json | jq -rs '
  def secs: split(".")[0] | rtrimstr("Z") + "Z" | fromdateiso8601;
  ["agent","status","secs","in","out","cache"],
  (.[] | [ .subTask.profile, .status,
           ((.finishedAt // .startedAt | secs) - (.startedAt | secs)),
           (.usage.inputTokens // 0), (.usage.outputTokens // 0),
           ((.usage.cacheCreateTokens // 0) + (.usage.cacheReadTokens // 0)) ])
  | @tsv' | column -t

agent              status  secs  in     out  cache
support-triage-pi  ok      3     3      89   4459
support-triage     ok      6     12064  204  0

The cache column is why a single token number misleads. Both runs did the same work on the same model, but pi reports almost all of its input on the cache lane and marlin folds it into in. Add in and cache together before you compare anything. And for what each one cost, ask the sessions. A run has no price of its own, but orca run opens a fresh session per run unless you pass --session, so here one session is one run:

orca sessions list --json | jq -r '.[0:2][] | [.profile, .costUsd, .costState] | @tsv'

support-triage-pi   0.022582   estimated
support-triage      0.051585   estimated

estimated means the run is priced from the recorded rate schedule and has not been reconciled against the provider’s own billing yet, so treat it as close rather than final. Compare those two runs, not the agents: orca stats agents and orca usage aggregate every run an agent has ever done, so an agent you have been poking at all afternoon will look far more expensive than one you created a minute ago. They answer a different question, which is where your credit went. Read the answers too, not only the numbers. Whether the reply is actually right is the comparison that survives every accounting difference. For where your credit went across everything, rather than a single run:

orca usage --window 24h --meter cost

Swap pi for claude, codex or vercel in the second file to compare against those SDKs the same way; the runtimes and their model id formats are listed on Agent profiles. On our own 48-task suite, one model through one gateway, Orcacode finished the work on 1.9x fewer tokens than Pi and 5.2x fewer than Claude Code; the method and the numbers are in the token economics post. Your prompt, on your tickets, is the number that matters.

Get Started

Core Concepts

Guides

Runbooks

1 and 2. Sign in, build an agent

3. Publish and use it

4 and 5. Orcacode, then compare

2. Your first agent, on the harness

3. Publish it and use it

4. Orcacode, in your terminal

5. Compare it with another harness

1 and 2. Sign in, build an agent

3. Publish and use it

4 and 5. Orcacode, then compare

​1. Sign in

​2. Your first agent, on the harness

​3. Publish it and use it

​4. Orcacode, in your terminal

​5. Compare it with another harness

1. Sign in

2. Your first agent, on the harness

3. Publish it and use it

4. Orcacode, in your terminal

5. Compare it with another harness