> ## Documentation Index > Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start here > Sign in, build your first agent on the Orca Harness from the terminal, publish it, run the same harness locally with Orcacode, then compare it with another harness. 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. Get a workspace, sign the CLI in, and create your first agent from a YAML file on the Orca Harness runtime. Put the agent behind an endpoint with its own key, and call it from curl, the CLI or an SDK. Run the same harness locally on your repo, then run one prompt on two harnesses and read the numbers. *** ## 1. Sign in No account yet? Sign up at [app.orcapods.ai/sign-up](https://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](https://app.orcapods.ai). ```bash theme={"dark"} 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](/cli/authentication). ```bash theme={"dark"} 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: ```bash theme={"dark"} 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. ```bash theme={"dark"} 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. ```bash theme={"dark"} 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: ```bash theme={"dark"} 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](/cli/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. ```bash theme={"dark"} 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. ```text theme={"dark"} 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: ```bash bash and zsh theme={"dark"} 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 ``` ```bash fish theme={"dark"} 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 ``` ```bash theme={"dark"} 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](/guides/publishing) and the [Chat Gateway API](/api-reference/chat-gateway). ```bash theme={"dark"} orca chat support "Ticket #4414: I cannot sign in since the password reset." --key "$CHAT_KEY" ``` Pick the one for your stack, not both: ```bash TypeScript theme={"dark"} npm install @orcapods/sdk ``` ```bash Python theme={"dark"} 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](/sdk/overview). You have an endpoint. Put the agent on a schedule with [Automations](/concepts/automations), share it as a kit from [Shared templates](/concepts/templates), and watch spend on the Usage page ([Credits and billing](/concepts/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. ```bash theme={"dark"} 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: ```bash theme={"dark"} orcacode --bare --no-session -p "List the files here and say in one sentence what this project is." ``` ```text theme={"dark"} • 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](https://orcapods.ai/orcacode/docs/#start). 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: ```bash theme={"dark"} 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: ```bash theme={"dark"} 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: ```bash theme={"dark"} 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 ``` ```text theme={"dark"} 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: ```bash theme={"dark"} orca sessions list --json | jq -r '.[0:2][] | [.profile, .costUsd, .costState] | @tsv' ``` ```text theme={"dark"} 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: ```bash theme={"dark"} 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](/concepts/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](https://orcapods.ai/blog/introducing-orcacode). Your prompt, on your tickets, is the number that matters.