Dashboard and API

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

1. Create your account

Go to www.orcapods.ai and create an account.

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.

Open the dashboard

You’ll land in the dashboard at app.orcapods.ai.

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.

Open All agents, then Create agent

In the sidebar under Build, open All agents, then click Create agent.

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.

Create it

Save. Your agent appears in the Agents table, ready to run.

3. Run it

Open the Workbench

In the sidebar under Build, open Workbench.

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

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.

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.

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.

Create an agent and run it

The dashboard and API share the same surface. Anything you did above you can do here.

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"

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);
    }
  }
}

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"))

You’ll see a stream of RunEvent objects:

{"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 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 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?

Run Orca locally

Clone the repo and bring up the full stack with Docker Compose or individual processes. Best for development, evaluation, or air-gapped deployments.

What’s next

Agent profiles

Tools, skills, MCP servers, sandboxes, and file policy.

Workflows

Orchestrate multiple agents as a DAG.

Publish an agent

Expose an agent as a chat endpoint for your app.

Get Started

Core Concepts

Guides

Runbooks

Dashboard and API

1. Create your account

2. Build your first agent

3. Run it

4. Call it from the API

Meet Sonar, the built-in helper agent

Prefer to self-host?

Run Orca locally

What’s next

Agent profiles

Workflows

Publish an agent

​1. Create your account

​2. Build your first agent

​3. Run it

​4. Call it from the API

​Meet Sonar, the built-in helper agent

​Prefer to self-host?

Run Orca locally

​What’s next

Agent profiles

Workflows

Publish an agent

1. Create your account

2. Build your first agent

3. Run it

4. Call it from the API

Meet Sonar, the built-in helper agent

Prefer to self-host?

What’s next