> ## 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.

# Use Orca from Claude Code

> Install the Orca plugin, sign in headlessly, and drive cloud agents from a Claude Code session.

Claude Code can operate Orca end to end: install the CLI, log in without a browser on the machine, create agents, run them in the cloud, and follow their output. Two setup routes, pick one.

## Route 1: the Orca plugin (recommended)

The plugin ships the `use-orca` skill (which teaches Claude the golden paths) and auto-registers the Orca MCP server for every session:

```bash theme={null}
claude plugin marketplace add okikorg/orca-cli
claude plugin install orca@orca
```

## Route 2: MCP server only

If you already have the `orca` CLI installed and signed in:

```bash theme={null}
claude mcp add orca -- orca mcp serve
```

## First run

Inside a Claude Code session, ask for anything Orca-shaped, for example: "create an Orca agent that triages my support inbox and run it against these three sample tickets."

Claude will walk the loop itself:

1. `orca doctor --json` to check the install, then `curl -fsSL https://orcapods.ai/install.sh | sh` if the CLI is missing.
2. `orca login`: in an agent context this automatically uses the device flow. Claude relays a one-time code and a URL; you open the URL on any device, check the code matches, and approve. The CLI picks up its key by polling; no key ever passes through the chat.
3. `whoami`, `create_agent`, `run_agent`, `wait_for_run` over MCP (or the `--json` CLI equivalents) to do the work.

## A worked transcript

```text theme={null}
user: run my support-triage agent against the new tickets and summarize

claude: [tool: whoami] -> tenant acme, role member
claude: [tool: run_agent {agent: "support-triage", prompt: "..."}]
        -> {runId: "run_7f2", sessionId: "sess_9a1"}
claude: [tool: wait_for_run {runId: "run_7f2", timeoutSeconds: 120}]
        -> {status: "ok", done: true, events: [...]}
claude: The agent processed 14 tickets: 3 urgent (billing), 9 routine, 2 spam. ...
```

## Notes

* The MCP server resolves credentials lazily (flag, then `ORCA_API_KEY`, then the CLI context config), so registering it before the first login is fine; tools answer with the exact fix until you sign in.
* Everything not covered by a dedicated tool is reachable through the `api_request` tool, documented by the live spec at the `orca://openapi` resource.
* Headless auth details, including CI: [Headless authentication](/agents/headless-auth).