Quickstart

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 Agents → New agent

In the sidebar under Build, open Agents, then click New agent.

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.

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 ⌘/Ctrl + Enter.

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.

See the Workbench guide 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.

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.

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

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

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

Dashboard Guide

A tour of every screen in the product.

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

1. Create your account

2. Build your first agent

3. Run it

4. Call it from the API

Meet Orca, the built-in helper agent

Prefer to self-host?

Run Orca locally

What’s next

Dashboard Guide

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 Orca, the built-in helper agent

​Prefer to self-host?

Run Orca locally

​What’s next

Dashboard Guide

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 Orca, the built-in helper agent

Prefer to self-host?

What’s next