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

# Dashboard and API

> Build and run your first agent by clicking, then call the same agent from your own code with curl, TypeScript or Python.

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 All agents, then Create agent">
    In the sidebar under **Build**, open **All agents**, then click **Create agent**.
  </Step>

  <Step title="Fill in the basics">
    * **Name**: e.g. `researcher`
    * **Runtime**: choose `vercel` (multi-provider) for this walkthrough
    * **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 **Enter** to send (Shift+Enter inserts a newline).
  </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>

## 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, then Infrastructure, then API Keys**, click **New API key**. Copy
    the `${ORCA_API_KEY}` 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={"dark"}
      export ORCA_API_KEY="${ORCA_API_KEY}"

      # 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."
        }'
      # Returns: { "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={"dark"}
      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={"dark"}
      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={"dark"}
{"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 Sonar, the built-in helper agent

Every workspace gets Sonar automatically: it's seeded the first time you (or the dashboard) list
your agents, so no setup step is required. It runs on the `marlin` runtime (sandbox worker mode)
and answers questions about the product from the documentation site. It cannot act on your
workspace: it cannot create agents, manage pods, register MCP servers, or diagnose runs on your
behalf.

Sonar appears in your agent list like any other agent. Open the Workbench, select it, and ask. It
carries a single skill, `sonar-guide`, which answers from the documentation site.

Sonar can never read or set secret values. For MCP credentials it always points you to the
[Secrets](/concepts/secrets) page. Sonar is locked: it can be read and pinned, but editing or
deleting its profile is refused. If it's ever missing or drifted, `POST /api/orca/seed` restores
it to defaults; that route keeps the orca name because it is the platform's, not the agent's.

Capability bundles like `@profiles`, `@pools.admin`, `@mcp`, and `@skills` exist for any agent to
opt into, but Sonar itself does not use them: its tools are `web_search`, `web_extract`, and
`time_now`.

Sonar was previously named `orca`. Workspaces created before the rename have theirs retired
automatically the next time their agents are seeded: the old agent and its `orca-guide` skill are
removed once Sonar is in place. Sessions, runs and usage records name the agent as text rather
than by a foreign key, so that history survives the removal and stays readable. A workspace with
the old agent still running keeps it until nothing is in flight.

***

## 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="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>