Documentation

Everything you need to build with Orkestra.

# Quick Start

Get your first AI-generated project running in under 2 minutes.

Create an account

curl -X POST https://api.cesaflow.ai/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "secret", "organization_name": "My Org"}'

# Response:
# { "api_key": "sk_...", "org_id": "..." }

Start a run

curl -X POST https://api.cesaflow.ai/api/v1/runs \
  -H "x-api-key: sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"objective": "Build a FastAPI todo app with JWT auth", "project_id": "my-todo"}'

# Response:
# { "run_id": "abc-123", "status": "pending" }

Watch it build

# Poll for status
curl https://api.cesaflow.ai/api/v1/runs/abc-123 \
  -H "x-api-key: sk_YOUR_KEY"

# Or connect WebSocket for live events:
# wss://api.cesaflow.ai/ws/runs?api_key=sk_YOUR_KEY

# Download when done:
curl https://api.cesaflow.ai/api/v1/runs/abc-123/download \
  -H "x-api-key: sk_YOUR_KEY" -o workspace.zip

# REST API Reference

Base URL: https://api.cesaflow.ai
Auth header: x-api-key: sk_YOUR_KEY

Endpoints

POST

/api/v1/auth/register

Create an account and get an API key

POST

/api/v1/auth/login

POST

/api/v1/runs

Start a new run (returns run_id immediately)

🔑 auth

GET

/api/v1/runs

List all runs for your org

🔑 auth

GET

/api/v1/runs/{run_id}

Get run status, nodes, and files

🔑 auth

GET

/api/v1/runs/{run_id}/download

Download workspace as ZIP

🔑 auth

GET

/api/v1/benchmark/tasks

List all benchmark tasks

🔑 auth

POST

/api/v1/benchmark/run

Start a benchmark run

🔑 auth

GET

/api/v1/benchmark/{id}

Poll benchmark results

🔑 auth

GET

/api/v1/billing/usage

Get monthly usage and budget

🔑 auth

/ws/runs?api_key=KEY

WebSocket: stream live run events

🔑 auth

Example: Start a Run with project_id

curl -X POST https://api.cesaflow.ai/api/v1/runs \
  -H "x-api-key: sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Add WebSocket support to the chat feature",
    "project_id": "my-chat-app"
  }'

# If project_id exists:
# - Reuses /workspace/project_my-chat-app/ (files preserved)
# - Loads previous plan and file history
# - Planner knows what was already built

WebSocket Events

// Connect: wss://api.cesaflow.ai/ws/runs?api_key=sk_KEY

// Events streamed:
{ "event": "run_started",   "run_id": "...", "node_count": 4 }
{ "event": "token_chunk",   "agent": "backend", "chunk": "..." }
{ "event": "file_written",  "agent": "backend", "path": "main.py", "bytes": 1240 }
{ "event": "run_completed", "run_id": "...", "files": ["main.py", ...] }
{ "event": "human_input_required", "question": "Which database?" }

# CLI Reference

Install the CLI for terminal-first workflows.

Install

cd cli/
pip install -e .

# Or with pipx:
pipx install -e .

aios run — Start a task

aios run "Build a REST API for a blog"
aios run "Add JWT auth" --project my-blog
aios run "Build a FastAPI app" --tasks backend,qa   # select agents
aios run "..." --model gpt-4o                       # override model

aios benchmark — Run SWE-Bench Lite

aios benchmark              # run all 10 tasks
aios benchmark --list      # list available tasks
aios benchmark --tasks hello_world,calculator  # run specific tasks

aios logs — Stream live run events

aios logs <run-id>          # stream events for a run
aios logs <run-id> --follow  # keep streaming until done

Environment Variables

AIOS_API_KEY=sk_...      # your API key
AIOS_API_URL=https://api.cesaflow.ai  # API base URL (default)
OPENAI_API_KEY=sk_...   # for agents to call LLMs
GITHUB_TOKEN=ghp_...    # for git/PR tools (optional)
PLAYWRIGHT_ENABLED=1    # enable browser tool (optional)

# Agent Tools

All tools available to agents during a run. Agents choose which tools to call based on the task.

Files

write_file

Write content to a file in the workspace.

params: path: string, content: string

Files

read_file

Read the contents of a workspace file.

params: path: string

Files

list_files

List all files in the workspace.

Shell

run_command

Execute a shell command (pip install, pytest, npm, etc.).

params: command: string

Shell

read_test_output

Read the output of the last run_command call.

Web

web_search

Search the web via DuckDuckGo for documentation or packages.

params: query: string

Browser

browser_navigate

Navigate to a URL (Playwright or httpx fallback).

params: url: string

Browser

browser_get_content

Read text content of the current page.

Browser

browser_click

Click an element on the current page.

params: selector: string

Browser

browser_screenshot

Take a screenshot of the current page (base64 PNG).

Git

git_init

Initialize a git repo and make the first commit.

params: message?: string

Git

git_status

Run git status and show last 5 commits.

Git

github_create_pr

Open a pull request via GitHub API (requires GITHUB_TOKEN).

params: owner, repo, title, body, head, base

# Architecture

How Orkestra runs your task from start to finish.

Agent Pipeline

POST /api/v1/runs
       │
       ▼
  GraphScheduler
       │
  Wave 1: ┌─────────┐
          │ Planner │  ← generates API Contract
          └─────────┘
               │
  Wave 2: ┌─────────┐   ┌──────────┐
          │ Backend │   │ Frontend │  ← run in PARALLEL
          └─────────┘   └──────────┘
               │               │
  Wave 3:      └───────┬───────┘
                  ┌────┴────┐
                  │   QA    │  ← waits for both
                  └─────────┘

Self-Debugging Loop

Agent runs → validates (pytest/syntax check)
    │
    ├─ PASS → next wave
    │
    └─ FAIL → inject debug_info into prompt
                  {
                    error_type: "validation_failure",
                    failed_command: "pytest tests/",
                    full_output: "...",   // full pytest output
                    failed_tests: [...],  // parsed test names
                    attempt: 2
                  }
              → agent retries (max 3 attempts)

Project Memory

project_id = "my-blog"

Workspace:  /workspace/project_my-blog/   ← shared, persistent
DB key:     project:my-blog:state         ← PostgreSQL project_memory

State stored:
  { project_id, total_runs, files[], runs[{objective, files, ts}] }

Next run with same project_id:
  → Planner sees: "Continuation of project, existing files: [...]"
  → DO NOT rewrite — build on top

# Benchmark

Orkestra includes a built-in benchmark suite: 10 coding tasks evaluated automatically, no human grading.

Task List

hello_worldtrivialWrite a Python hello world script

calculatoreasyImplement a calculator with unit tests

fastapi_healtheasyCreate a FastAPI app with /health endpoint

todo_apimediumFull CRUD todo API with SQLite

data_processingmediumCSV processing pipeline with pandas

auth_jwtmediumJWT authentication system

websocket_chathardReal-time WebSocket chat server

async_scraperhardAsync web scraper with rate limiting

react_componentmediumReact data table component

docker_composemediumMulti-service docker-compose setup

Scoring

Each task: 10 points max
Check types:
  file_exists       — does the required file exist?
  file_contains     — does it contain the expected code?
  any_file_contains — does any file contain the pattern?

Score = (passed_checks / total_checks) * 10
Grade: S (90+) · A (80+) · B (70+) · C (60+) · D (50+) · F (<50)

🏆 Run Benchmark Now

# FAQ

Which AI models does Orkestra use?

By default, Orkestra uses Qwen Plus (DashScope) — no API key needed for new users. You can override this with any model via Dashboard → Model Settings: Gemini, Claude, Groq, Mistral, DeepSeek, Ollama, and more are all supported.

Is GITHUB_TOKEN required?

No. Git tools (git_init, git_status) work without it. You only need GITHUB_TOKEN for github_create_pr — opening pull requests via the GitHub API.

Is the browser tool always active?

Browser navigation with Playwright requires PLAYWRIGHT_ENABLED=1 in your environment. Without it, browser_navigate falls back to plain HTTP via httpx — no JavaScript rendering.

How does project_id work?

When you pass project_id to a run, Orkestra reuses the same workspace directory (/workspace/project_{id}/) so files persist across runs. The Planner also loads previous run history and tells agents not to overwrite existing code.

Can I bring my own model (BYOM)?

Yes. Go to Dashboard → Model Settings and enter your API key for any supported provider. Orkestra will use your credentials for all runs.

How do I run Orkestra locally?

Clone the repo and run: docker compose up -d. No API key needed — Orkestra ships with a built-in Qwen system key. For your own models, add keys via Model Settings. Backend: port 8001, Frontend: port 3000.