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

# Quickstart

> Create your account, build your first agent in the dashboard, run it, then call it from the API.

This guide takes you from sign-up to a running agent — first in the dashboard, then from the API.

## 1. Create your account

<Steps>
  <Step title="Sign up">
    Go to [www.orcapods.ai](https://www.orcapods.ai) and create an account.
  </Step>

  <Step title="Create or join an organization">
    Orca is multi-tenant: everything you create lives inside an **organization** (your workspace).
    Create a new one or accept an invite. You can switch organizations at any time.
  </Step>

  <Step title="Open the dashboard">
    You'll land in the dashboard at [app.orcapods.ai](https://app.orcapods.ai).
  </Step>
</Steps>

## 2. Build your first agent

An **agent** (also called a *profile*) is a reusable template: a runtime, a model, a system prompt,
and the tools it can use.

<Steps>
  <Step title="Open Agents → New agent">
    In the sidebar under **Build**, open **Agents**, then click **New agent**.
  </Step>

  <Step title="Fill in the basics">
    * **Name** — e.g. `researcher`
    * **Runtime** — choose `vercel` (multi-provider) for this quickstart
    * **Model** — e.g. `anthropic:claude-haiku-4-5`
    * **System prompt** — `You are a research assistant. Be concise.`
    * **Tools** — leave the default bundle (`@default`) selected

    Skills, MCP servers, sandboxes, and file mounts are optional — see
    [Agent profiles](/concepts/profiles).
  </Step>

  <Step title="Create it">
    Save. Your agent appears in the Agents table, ready to run.
  </Step>
</Steps>

## 3. Run it

<Steps>
  <Step title="Open the Workbench">
    In the sidebar under **Build**, open **Workbench**.
  </Step>

  <Step title="Pick your agent and prompt it">
    Select the `researcher` agent, type a prompt like *"Explain agent orchestration in three concise
    bullets,"* and press **⌘/Ctrl + Enter**.
  </Step>

  <Step title="Watch it stream">
    Events stream live — progress, the assistant's response, tool calls, and token usage. Use the
    **Transcript** and **Debug** tabs, filter by event kind, and export the run as Markdown or JSON.
  </Step>
</Steps>

See the [Workbench guide](/dashboard/workbench) for everything on this screen.

## 4. Call it from the API

For application code and automation, authenticate with an **`ao_` API key** and call the control
plane at `https://api.orcapods.ai`.

<Steps>
  <Step title="Create an API key">
    In the sidebar under **Settings → API Keys**, click **New API key**. Copy the `ao_…` token —
    it's shown only once. The key inherits your role. See [API Keys](/concepts/api-keys).
  </Step>

  <Step title="Create an agent and run it">
    The dashboard and API share the same surface — anything you did above you can do here.

    <CodeGroup>
      ```bash cURL theme={null}
      export ORCA_API_KEY="ao_live_..."

      # Create an agent (or reuse the one from the dashboard)
      curl -X POST https://api.orcapods.ai/api/profiles \
        -H "Authorization: Bearer $ORCA_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "researcher",
          "runtime": "vercel",
          "model": "anthropic:claude-haiku-4-5",
          "systemPrompt": "You are a research assistant. Be concise.",
          "tools": ["@default"]
        }'

      # Submit a run
      curl -X POST https://api.orcapods.ai/api/runs \
        -H "Authorization: Bearer $ORCA_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "profile": "researcher",
          "title": "Short summary",
          "prompt": "Explain agent orchestration in three concise bullets."
        }'
      # → { "runId": "run-abc123", "sessionId": "sess-a1b2c3d4" }

      # Stream events
      curl -N https://api.orcapods.ai/api/runs/run-abc123/stream \
        -H "Authorization: Bearer $ORCA_API_KEY" \
        -H "Accept: text/event-stream"
      ```

      ```typescript TypeScript theme={null}
      const BASE = "https://api.orcapods.ai";
      const headers = {
        Authorization: `Bearer ${process.env.ORCA_API_KEY}`,
        "Content-Type": "application/json",
      };

      // Submit a run
      const { runId } = await fetch(`${BASE}/api/runs`, {
        method: "POST",
        headers,
        body: JSON.stringify({
          profile: "researcher",
          title: "Short summary",
          prompt: "Explain agent orchestration in three concise bullets.",
        }),
      }).then((r) => r.json());

      // Stream events (fetch, so you can send an Authorization header)
      const res = await fetch(`${BASE}/api/runs/${runId}/stream`, {
        headers: { ...headers, Accept: "text/event-stream" },
      });
      const reader = res.body!.getReader();
      const decoder = new TextDecoder();
      let buffer = "";
      for (;;) {
        const { done, value } = await reader.read();
        if (done) break;
        buffer += decoder.decode(value, { stream: true });
        let i;
        while ((i = buffer.indexOf("\n\n")) !== -1) {
          const block = buffer.slice(0, i);
          buffer = buffer.slice(i + 2);
          const data = block
            .split("\n")
            .filter((l) => l.startsWith("data:"))
            .map((l) => l.slice(5).trimStart())
            .join("\n");
          if (data) {
            const event = JSON.parse(data);
            console.log(event.type, event.message);
          }
        }
      }
      ```

      ```python Python theme={null}
      import json, os, requests

      BASE = "https://api.orcapods.ai"
      headers = {
          "Authorization": f"Bearer {os.environ['ORCA_API_KEY']}",
          "Content-Type": "application/json",
      }

      run = requests.post(
          f"{BASE}/api/runs",
          headers=headers,
          json={
              "profile": "researcher",
              "title": "Short summary",
              "prompt": "Explain agent orchestration in three concise bullets.",
          },
      ).json()

      with requests.get(
          f"{BASE}/api/runs/{run['runId']}/stream",
          headers={**headers, "Accept": "text/event-stream"},
          stream=True,
      ) as resp:
          for line in resp.iter_lines(decode_unicode=True):
              if line and line.startswith("data:"):
                  event = json.loads(line[5:].strip())
                  print(event.get("type"), event.get("message"))
      ```
    </CodeGroup>
  </Step>
</Steps>

You'll see a stream of `RunEvent` objects:

```json theme={null}
{"type":"progress","message":"Starting run...","ts":"2026-07-28T10:00:00Z"}
{"type":"assistant","message":"Agent orchestration coordinates...","ts":"..."}
{"type":"result","message":"- It routes tasks to specialized agents...","ts":"..."}
{"type":"usage","usage":{"inputTokens":1240,"outputTokens":380},"ts":"..."}
```

The typed [SDKs](/sdk/overview) wrap exactly this surface for TypeScript, Python, and Go.

***

## Meet Orca, the built-in helper agent

Every workspace ships with a seeded agent named **Orca**. It runs on the `vercel` runtime and has
platform-management capabilities attached, so it can create agents, manage pools, register MCP
servers, and diagnose failing runs on your behalf.

Orca appears in your agent list like any other agent. Open the Workbench, select it, and ask —
it picks the right skill for the job:

* `orca-onboard-tenant` — guides a brand-new workspace from goal to first agent.
* `orca-diagnose-run` — pulls a run's events and classifies what went wrong.
* `orca-design-agent-from-goal` — turns a description into an agent and creates it.
* `orca-audit-pool-health` — checks a pool's members and proposes cleanup.

Orca can never read or set secret values — for MCP credentials it always points you to the
[Secrets](/dashboard/secrets) page. You can edit Orca like any agent, or reset it to defaults with
`POST /api/orca/seed`. The capability bundles it uses (`@profiles`, `@pools.admin`, `@mcp`,
`@skills`) aren't Orca-specific — any agent can opt into them.

***

## Prefer to self-host?

<Card title="Run Orca locally" icon="server" href="/guides/local-development">
  Clone the repo and bring up the full stack with Docker Compose or individual processes. Best for
  development, evaluation, or air-gapped deployments.
</Card>

***

## What's next

<CardGroup cols={2}>
  <Card title="Dashboard Guide" icon="table-columns" href="/dashboard/overview">
    A tour of every screen in the product.
  </Card>

  <Card title="Agent profiles" icon="id-card" href="/concepts/profiles">
    Tools, skills, MCP servers, sandboxes, and file policy.
  </Card>

  <Card title="Workflows" icon="sitemap" href="/concepts/workflows">
    Orchestrate multiple agents as a DAG.
  </Card>

  <Card title="Publish an agent" icon="globe" href="/concepts/publishing">
    Expose an agent as a chat endpoint for your app.
  </Card>
</CardGroup>