Platform Overview

Orquesta is a collaborative prompt orchestration platform that turns natural language prompts into production code. Your team writes what they want built, AI agents handle the code, PRs, and deployment.

The platform supports multiple execution paths: a local agent connected via WebSocket for full Claude CLI capabilities, cloud VMs with direct SSH execution, Batuta AI for autonomous task routing, and an External Agents API for third-party AI integration.

Quick Start

Get running in under 5 minutes:

npm install -g orquesta-cli orquesta-agent\norquesta-agent --token YOUR_PROJECT_TOKEN

Onboarding Tour

New users get an interactive guided tour on their first dashboard visit. The tour creates a demo project with sample data and walks through 9 key areas of the platform.

Core Concepts

Local Agent

The orquesta-agent package connects your local machine to the Orquesta dashboard via WebSocket. It receives prompts, executes them using Claude CLI, and streams logs back in real-time.

# Install globally (orquesta-cli gives the `orquesta` command, orquesta-agent the daemon)\nnpm install -g orquesta-cli orquesta-agent\n\n# Or use npx (not recommended for VMs — can timeout)\nnpx orquesta-agent --token YOUR_TOKEN

Connecting to a Project

Generate a token from the dashboard (Project → Agent → Setup), then:

orquesta-agent --token oat_abc123...

Multi-Agent per Project

Connect multiple agents to the same project — one on your dev laptop, another on staging, another on prod. Each agent gets its own token and runs independently.

# Dev laptop
orquesta-agent --token oat_dev_token --name "Dev Laptop"

# Staging server
orquesta-agent --token oat_staging_token --name "Staging VM"

# Production server
orquesta-agent --token oat_prod_token --name "Prod Server"

When submitting a prompt, you can choose which agent runs it via the agent selector dropdown. Features:

• Per-agent online/offline status with green indicators
• Agent selector dropdown when multiple agents are online
• Parallel execution — each agent runs prompts independently
• Custom agent names via --name flag

The agent will:

• Validate the token with the Orquesta API
• Establish a WebSocket connection via Supabase Realtime
• Send heartbeats every 30 seconds
• Listen for EXECUTE commands on the project channel
• Report its version and capabilities to the dashboard

Prompt Execution Flow

When a prompt is submitted:

1. Dashboard broadcasts an EXECUTE command via Realtime channel
2. Agent receives it, queues it (sequential execution only)
3. Agent spawns claude CLI process with the prompt
4. Output streams as log entries back to Supabase
5. On completion, agent reports status, git commits, and token usage

Coding engine — which CLI runs your prompts

The agent doesn't contain a model. It spawns a coding CLI that's already installed and logged in on the machine, so every prompt runs on your subscription. Pick the engine per project in Settings → Agent, from the chip in the project header, or in the setup wizard while you connect the agent — the wizard shows the same picker and the same marks, so the engine is chosen before the first prompt instead of after it fails.

# Cursor's headless agent — install once on the agent machine
curl https://cursor.com/install -fsS | bash
cursor-agent login

# Windows (PowerShell)
irm 'https://cursor.com/install?win32=true' | iex

# AWS Kiro CLI — macOS / Linux, install once on the agent machine
curl -fsSL https://cli.kiro.dev/install | bash
kiro-cli login          # AWS Builder ID (free) or IAM Identity Center
kiro-cli whoami         # what the agent checks to show the login mark

The choice reaches a running agent on its next heartbeat — no restart. The agent reports back which engine it is actually running, so if the one you picked isn't installed the dashboard shows the fallback instead of silently pretending. Each completed prompt is tagged with its cli_type and shows a badge in the timeline.

Two different problems get two different marks in Settings → Agent. ✗ means the engine is not installed — the agent falls back to the next one it has. ! means it is installed but not logged in: nothing falls back, because the binary is there, so prompts run and fail on the engine's own auth until you run its login on that machine (cursor-agent login, claude login, kiro-cli login). Each engine owns its credential — Orquesta never sees it and cannot log in for you.

IDE Hooks — mirror Claude Code and Cursor sessions

The flow above is dispatch: Orquesta sends work down to the agent. Hooks are the opposite direction — you keep working in your own IDE and Orquesta mirrors what happened. Nothing is ever executed back into your editor, and no daemon needs to be running.

Run this once per repo. Without --client it wires both tools:

# Claude Code + Cursor
orquesta-agent init --token oat_abc123...

# Only one of them
orquesta-agent init --token oat_abc123... --client cursor
orquesta-agent init --token oat_abc123... --client claude

It writes .orquesta.json (project binding — keep it gitignored, it holds the raw token) plus .claude/settings.json and/or .cursor/hooks.json. Existing hooks are preserved; re-running init upgrades Orquesta's entries instead of stacking duplicates.

Mirrored prompts land with source: terminal and a Local CLI badge; the cli_type column (claude-code or cursor-cli) drives the tool badge next to it. They are excluded from agent dispatch, so a hooked session is never re-executed.

Troubleshooting

Dashboard

The dashboard is the central hub for managing projects, submitting prompts, monitoring execution, and collaborating with your team.

Home (/dashboard/home) is a chat-first view: pick a project from the switcher and talk to its agent. The left rail lists your history grouped by day — Home chats, interactive terminal sessions, local hook sessions and single prompts — and a new account lands here with a ready-made first project and a four-step setup checklist (machine ready, pick your model, first prompt, invite someone — GitHub, Supabase and the rest live in Advanced mode). Each project has its own address, /dashboard/home/<projectId>. Switching from Advanced keeps the project you were on. Once a project has some history its starter suggestions come from it — open Auto Agent proposals first, then follow-ups to recent work. The right rail can be hidden, and holds an Activity panel (the tools the agent is running, as in interactive sessions) and an Artifacts panel (files the AI changed and links it produced). The sidebar's Operator / Advanced switch moves between Home and the full dashboard; Home only shows where the agent runs, and reconfiguring it is done in Advanced mode. Each Home chat works like a chat: on Claude CLI (agent 0.2.267+) every chat is one real Claude session, resumed with each new message, so Claude keeps the whole conversation — what it read, ran and answered — and "yes, do it" refers to what was just discussed. On other CLIs, older agents, or a machine that has never seen the chat, the message carries the chat's earlier turns instead (last 8, trimmed to fit). An agent's logs open in place under its answer, live while it works, without leaving the chat. The same chats are in Orquesta Terminal: its Operator button opens them full-screen over your panes, so you can download Terminal, sign in and talk to any project's agent without opening the dashboard. Home is available in English, Spanish and Portuguese. A project's Settings → Integrations tab groups everything it is wired to — Code (GitHub, with the linked repository and the PR feedback loop), Ship (Vercel, Supabase), Work intake (Linear, Slack, Telegram) and Talent (Derplins) — each with its status, what it is linked to and a disconnect button; skills and custom setups sit under Advanced. The old setup wizard is retired: links with ?setup=true land on that tab, or on the VM view for hosting.

Free Orquesta machine. Accounts signed in with Google can get one free cloud machine, from Home or when creating a project, with the agent and orquesta-cli preinstalled and the project set to run on Batuta. It sleeps after 48 hours without prompts and wakes up automatically when you send one; the prompt waits in the queue while it starts. Additional machines are paid, from the project's Agent tab.

Prompts & Execution

The Prompts tab is where you submit work for the AI agent. Each prompt can include:

• Content — Natural language description of what to build
• Tags — Categorize as bug, feature, refactor, urgent, docs
• Assignment — Assign to a specific team member
• Priority — Star important prompts
• Structured Specs — Use bug report, feature spec, or improvement templates with acceptance criteria

Prompts can come from multiple sources:

Management

The Management section includes:

• Tickets — Track work items from Linear integration or manual creation
• Requirements — Define and track project requirements with AI-assisted analysis
• QA — Quality assurance instructions and test tracking
• Planning — Create plans with items, milestones, and AI-generated breakdowns

Sound Cues

The dashboard plays short synthesized cues for outcomes — a run completing or failing, an agent connecting or dropping, and anything waiting on your input. Chrome is silent: opening a modal, toggling a switch or switching tabs never makes a sound. Agent and chat cues only play while the tab is in the background.

Turn them off, set the volume, or audition each cue in Profile → Sound. The preference is stored per device, and the whole set is silenced automatically if your system asks for reduced motion.

Logs & History

Real-time log streaming shows every step of agent execution — commands run, files modified, git operations, and more. Logs are categorized by level (info, warning, error) and type (command, output, status, git). The History page shows a chronological timeline of all project activity.

Live Activity

The side rail’s Activity tab — the first icon in the collapsible panel next to the terminal and next to the prompt timeline — reads what the agent is doing right now in plain language: “Edited public-queries.ts”, “Running the test suite”. The current step sits pinned at the top; under it is every step so far with the lines added and removed on each file, and a files changedsummary at the bottom.

It follows an interactive session live off the session stream, so it works for every CLI including orquesta-cli, and in the Prompts tab it follows the running prompt instead. It is the same stream as the Logs tab, read for people who do not want to read tool output: repeated file reads collapse into one line, bookkeeping steps are hidden, and a failed step shows the error instead of the raw payload. Nothing new is recorded to produce it.

Each step also carries a coloured area chip saying what it changes rather than which file it touched — Database, API, Interface,Dependencies, Deploy / CI, Config, Tests, Docs, or a red Destructive for deletions, drops and hard resets. A summary strip at the top of the panel adds them up, so “this run touched the database three times” is legible without opening a single file. Steps that only read something carry no chip, because reading changes nothing.

Artifacts — files the agent made

When a run produces something worth opening — an HTML report, a chart, a PDF, a CSV, a built site — the agent can publish it: orquesta-cli has a publish_artifact tool, and any CLI can simply write the file under .orquesta/artifacts/. When the prompt finishes, the agent (≥ 0.2.273) uploads those files and they appear first in the Operator's Artifacts card with a download link, kept for 30 days (max 25 MB per file, 50 files / 100 MB per prompt; .env and key-like files are never sent). On the on-demand microVM this is always on, because its disk dies with the session. On your own machines it is opt-in: Settings → Agent → Artifacts.

Each artifact, and each file in an interactive session's Context files pane, has two buttons: Open renders it in a new tab (HTML, images, PDF and text display instead of downloading; other types still download), and Share copies a public getorquesta.com/share/… link that anyone can open without an account. Rendering happens on a separate storage origin, never on getorquesta.com, so an AI-made page cannot touch your session. A link can be revoked from the same row, and an artifact's link stops working when the artifact expires.

Claude Code has no publish tool, so when it answers with an <antArtifact> block (an HTML page, an SVG, a Markdown doc) the block itself is saved as an artifact of that prompt a few seconds after it completes — no setting needed. New projects start with a short Use step in the setup card (chat, interactive session, standalone prompts, embed or hook) that decides where the project opens; its hosting step includes the Orquesta microVM, whose first 10 runs per organization are free (then $0.25/h).

Tasks in the side rail

The rail’s Tasks tab is one feed of everything waiting for work in this project — local tickets, plan items, Linear issues, scheduled prompts and prompts assigned to you — each tagged with where it came from, filterable by source.

Run does what the screen you are on means by running. In an interactive session it sends the task into the live terminal immediately. In the Prompts tab it dispatches to the agent: a task that already is a prompt row — a local ticket, a prompt assigned to you — runs in place, so the run stays attached to it and the ticket closes itself when it finishes; anything else becomes a new prompt. Beside it, Start loads the task into the prompt box for review instead of sending it, and Prompt first turns the story into a concrete implementation prompt.

Memory & Context

The Memory panel stores persistent project context that gets included in every prompt execution. This includes architectural decisions, coding conventions, known issues, and project-specific knowledge. Memory is automatically summarized and injected into the Claude CLI context.

Auto Context

Short prompts like "yes", "deploy", or "do it" automatically receive context from the last few completed tasks. No need to toggle Include Context — the agent always knows what came before. For longer prompts, use the Include Context toggle for explicit control.

The agent can also fetch detailed context mid-execution if it needs more information:

# Agent can call this during execution
curl -s https://getorquesta.com/api/agent/recent-context \
  -H "Authorization: Bearer $ORQUESTA_TOKEN" | jq .

Auto Agent

The Auto Agent analyzes your project — plans, recent work, memory, open tickets — and decides what to build next. It runs in two modes, both from the project's Auto Agent tab.

Background mode (propose & approve). Turn on the switch and pick a schedule. On each cycle the agent writes proposals — title, why it matters, the exact prompt to run, and a risk rating — into an inbox. It writes no code and executes nothing. You check the inbox once a day, edit any prompt if you want, and approve the ones worth doing; only then does the agent work. Rejected proposals are remembered, so it stops suggesting the same thing.

Cycles are cheap because most of them never happen: a cycle is skipped when your local agent is offline, when the inbox already has proposals waiting (draining it is your job — piling more on is just noise), and when nothing has changed since the last cycle (same commit, no new prompts). All three are decided by database reads, so a nominal "every 6 hours" on an idle project costs no tokens at all.

Run now (foreground). The original loop, under "Run now": the agent picks tasks and executes them immediately while you watch, up to the iteration limit you set. The loop runs server-side, so it survives tab switches, browser freezes, and deploys.

Autonomy (run without the click). Under Settings, "Run approved work automatically" lets proposals inside limits you set run with nobody clicking Approve. It is off by default and it will not turn on without a verification command — the command that proves your project still works (npm test, pytest -q, make check). Work nobody reviews and nothing verifies is not automation, so Orquesta refuses to do it.

Each autonomous run works on its own auto/… branch off your current commit, does the task, then runs your verification command. On exit 0 it settles the way your project's git workflow says — fast-forward and push, or open a pull request and leave the base branch alone. On any other exit code it reverts the branch, puts the repository back at the commit it started from, and returns the proposal to the inbox with the last 100 lines of the failure attached. It never retries: one machine attempt per proposal, then a human decides.

Four limits bound it. A risk ceiling and a size ceiling — anything above them still waits for you, and a proposal that never stated its risk is treated as medium, so it is blocked under the default. Two rolling 24-hour budgets, a task count and a dollar figure, whichever runs out first (flat-rate model plans genuinely cost nothing per run and report $0, so there the task count is what binds). And a circuit breaker that pauses the project after N consecutive failures and emails nobody a surprise — the tab says why, and you resume it from there.

Every unattended run is listed under "Autonomous runs" with its branch, the commit it started from, the verification exit code, whether the tree was put back, and the failure output. A run that failed and could not be reverted is called out in red — that is the one case worth looking at the machine for.

Workstreams (several standing questions, one project). A project rarely has one purpose. "Triage the bugs", "read customer feedback and decide what to build" and "look at marketing and commercial action" are three different questions, and asking them as one collapses into whichever the model finds most legible. Create workstreams under the project's Workstreams panel and the Auto Agent tab grows a selector: each stream gets its own schedule, its own inbox, its own limits and its own 24-hour budget, and each brain is told what its stream is for and asked to propose nothing rather than reach into another one.

A workstream may point at a directory, but it does not have to. The stream is what defines the work; the directory decides only whether two streams may run at the same moment. Streams in different directories run in parallel. Streams sharing one directory — and any stream against a project that is a single folder — take turns, because two autonomous branches in one working tree is a race nobody wins. A stream pointed at the project root is exclusive against every other, since it contains them.

That directory may sit below the repository root — a stream that owns repo/server can still branch, commit and roll back. Under filesystem isolation the sandbox makes only the working directory writable, so the agent also opens the enclosing repository's git directory (and, for a worktree, the main repository it writes objects into). Without it such a stream could edit code and never create a branch, and the error would read like a failing disk rather than a setting.

Each stream has a kind, because not every question ends in a commit. A Code stream changes the repository: it works on its own branch, must pass a verify command, and is rolled back if it does not. An Analysis stream reads and reports — customer feedback, error logs, the state of the market — and needs no verify command, because there is nothing to undo. An Action stream does something outside the repository, like sending an email or filing a ticket, and never runs unattended: it always waits for a person, whatever the autonomy setting says. Switching a stream to Action turns its autonomy off with it.

The swarm view. Once a project has two or more workstreams the Auto Agent tab draws them as a graph: the root agent at the top, a node per stream beneath it, with the kind, directory, inbox and 24-hour count on each. A green edge means that stream is running right now; an amber one means it is armed and standing still because another run is holding its directory — the queueing rule above, shown rather than described. You can pin the view either way from the project settings or when you create the project, for a project that will be a swarm before its first stream exists.

Click a node and a panel on the right shows what that stream is, what it last did and its recent runs; rename it from there by clicking its name. Drag the cards to arrange the graph however the project actually looks in your head — the arrangement is remembered in your browser, per project, and is yours alone: moving a card does not move it for anyone else. The reset control puts everything back.

Your terminal default. The same panel has Use as my terminal default: interactive sessions on that project then open in that workstream already selected (also settable with the star next to Run in in the terminal). It is a preference of yours, kept in your browser, not something the rest of the team inherits. The terminal header always names the workstream you are in (a page reload keeps it), and a session started in a workstream opens with that workstream's description loaded as its mission, so the agent starts from it instead of asking what to do (agent 0.2.265 or later).

Joining a running session keeps its past. When you join a session that is already live, or reload the page while one is running, the conversation so far is loaded into the terminal's scrollback (and the History panel) before the live screen is drawn, so scrolling up shows the earlier turns instead of only the last screenful. Claude sessions only, agent 0.2.266 or later.

Under the graph, What the swarm has done merges every stream into one chronology for the last fourteen days — proposals and runs interleaved, because a proposal and the run that came from it are one story — with the totals across the window: runs, verified, rolled back, and rollback failed counted apart from the rest, since that last one means a branch was left behind on the machine. Click any row to jump to the stream it came from.

A daily digest email lists what is waiting for review, and only goes out when something new arrived — an ignored proposal never becomes a daily nag.

Meet — a video call with the agent

Meet, under the project's Agent menu, is a one-click video call with your agent. Press "Start meet": the dashboard opens a call on meet.apuchat.com right inside the page and sends the agent to join it. Talk out loud — your speech is transcribed in your browser and reaches the agent as text; its answers are spoken back and also appear in the transcript next to the call, so nothing said is lost when the call ends.

Each project gets its own persistent meet room, separate from the team chat and coordination channels, so the agent is only woken into a call you started. "Invite" shows a protected link and password to bring someone else in; "Open in a new tab" runs the same call outside the dashboard if your browser blocks the microphone in an embedded page. The agent must be online to answer.

Past meets. Every meet held from the dashboard is recorded as text — who said what, when — and listed under the "Start meet" card with its date, duration and line count; open one to read the full transcript. The recording is the transcript only (no audio or video is stored), and it is written by the dashboard tab that is in the call, so a meet joined only from a plain browser tab is not kept.

On mobile. Meet is also in the Orquesta app: open a project, tap "Meet with the agent", and the call runs in-app the same way, with the live transcript and your past meets. If the agent runs the dispatch but does not stay in the room, the call view says "agent didn't join" rather than waiting silently — some projects decline a call by their own rules, and that is surfaced honestly.

How the agent answers. Each thing you say is answered by a fast model on Orquesta's side that reads what Orquesta already knows about the project — its notes, recent prompts and their results — so questions are answered in a second or two without touching your machine. When you ask for real work (look at the code, run the tests, check a log, change something), it says "one moment" and hands a normal prompt to the project's agent; while that runs you hear a short update every half minute, and the result is read out when it lands. The agent stays in the call while you talk or while work is in flight, and leaves after about three minutes of silence (30 minutes at most). Speaking again wakes it back in.

Hey Orquesta — hands-free voice across all your projects

Hey Orquesta (in the sidebar) is a voice companion that sits above every project you have access to — for when you are walking or driving and cannot read a screen. Turn on hands-free, and it listens, answers out loud and listens again.

• "How is ehive-dev doing?" — read from Orquesta: whether the agent is online, what is running and its latest log lines, and what finished recently. No agent is woken for this.
• "Tell the ehive-dev agent to run the tests" — becomes a normal prompt on that project, attributed to you, and the agent is woken right away. Needs permission to run prompts on the project.
• "Email me when ehive-dev finishes" — Orquesta emails you when the work in progress (or the task you just asked for) completes or fails, with a short summary of the result.

Speech recognition and the voice run in your browser (Chrome, Edge or Safari). Projects are matched by name, so a close-enough name works; if two projects match, it asks which one. The same endpoint, POST /api/companion/turn, accepts a dashboard session or an oclt_ CLI token, which is what the mobile app uses.

Hey Orquesta is included in the Pro and Max plans — you get it when any organization you belong to is on one. On other plans the screen shows an upgrade card and the endpoint answers 402.

Replies are spoken with the Grok voice (with the browser voice as fallback), and pick the language from the ES/EN switch on the screen. Every conversation is kept: the history button lists past ones and, inside one, shows what each agent did with the work you handed it (live status and result). When you ask how that work went, the companion reads the current result instead of guessing. The orb in the page header opens it from anywhere. In hands-free mode the microphone stays open while it talks, so you can cut in with a new request at any moment; while it thinks it says a short "one moment" instead of going silent.

Team Collaboration

Orquesta supports four roles with granular permissions:

Project Chat

Each project has a built-in real-time chat powered by Supabase Realtime. Features include threaded conversations, file attachments, read receipts, and typing indicators. Chat is ideal for discussing prompts, reviewing outputs, and coordinating work.

Ask the project agent. Type @agent in a project's chat and it answers from that project's own history — what ran last, how it went, what is still open. It only reports; it never runs anything, and it only knows the project it lives in. The handle is per-project — name it in Settings → Agent → Chat Handle (e.g. @elclaudio) — and it answers inside the thread you asked in. Answers come from the server, so they work even when the agent machine is offline.

Turn a message into a task. Hover any chat message and hit the task icon to open it as a plan item — title and description are prefilled from the message, and you pick the plan and the assignee. The task keeps a From chat badge so you can tell what was raised in conversation.

Start a meet. The Meet button in the chat header opens the project's video room and posts a Join card into the conversation, so anyone reading can jump in with one click. Video and audio go browser-to-browser — the room only carries the signalling, and nothing said in it is recorded. Each person gets their own link when they hit Join, which is why the card is a button rather than a URL to paste.

Agents asking agents

One project's agent can ask another's. Inside an organization an agent lists its peers with GET /api/agent/directory and sends a request with POST /api/agent/requests: a consulta (a question, runs read-only on the other side, approved automatically) or an encargo (a work order, waits for a human to approve it in the project's Callable tab). The request is an ordinary prompt on the target project, so it shows up in its history; when it finishes, the answer comes back to the asking project as a follow-up prompt, or the asker polls GET /api/agent/requests/{id}, which also hands out download links for files the target produced (up to 256 MB each). Chains are capped at two hops, loops are refused and each project has a daily cap. Only projects with coordination enabled (settings.coordination.enabled) are listed and may ask each other; a request takes an optional timeout_min (default 30 for a consulta, 240 for an encargo, max 720) after which it is cancelled, and an agent token can be bound to source IPs.

Permanent handles and DMs to the owner. Each project agent can hold a permanent @<project>-agent handle that never expires, with the owner on its allowlist. An agent blocked on a decision writes to an allowlisted person with POST /api/agent/dm; the reply, for up to 24 hours, becomes a prompt that shows the agent its own question and the task that asked it.

Agent Identity

Settings → Agent Identity is the single place that answers “who is this agent and how do I reach it”. Every address the agent answers on used to live on a different screen — the chat handle in Settings, the Apuchat @handle in Coordination, the email in the Inbox pane — so nobody could see the whole identity at once. This tab gathers all of it. Identity is per project, and the tab is owners and admins only.

Give the agent its own email. By default an agent's email is a disposable apumail inbox, which is right for handing an address to an external agent for one exchange and wrong for anything you want to keep receiving on — apumail releases it after 24h idle. Set an address here (any mailbox apumail serves, plus its inbox token) and that becomes the agent's email; the disposable inbox stays where it is and stops being the answer. The token is verified against apumail before it is saved, stored encrypted, and never shown again — a token that is merely saved fails later as a mailbox that looks empty instead of broken.

The configured address is the one the product uses. Once an identity email is set, the Inbox pane in an interactive session reads that mailbox instead of the disposable one and withdraws its own Replace/Release buttons: those would produce an address the agent does not answer on. Removing the identity mailbox is done here, where it was set.

One Apuchat callsign, not two. The @handle people ring is now also the callsign the agent presents when it joins coordination channels and video calls, so whoever rang @your-agent meets @your-agentin the room rather than a machine-generated name. If the handle stops working the agent falls back to a throwaway callsign and keeps joining, and you repair the published one from this tab: Renew revives it in place, and only a handle Apuchat has really dropped is replaced — the tab says so explicitly when the address changes, because anyone holding the old one has to be told.

The Callable & DM handle card is the same card everywhere it appears. It has its own entry in the Agent menu of the project bar, which is where to go when the job is managing callers rather than reading a channel; it still shows up in Coordination, where it has always lived; it is a section of Settings → Agents, next to the machine it rings; and it is folded into the Apuchat row of Agent Identity, so whoever came to ask how to reach the agent is not sent to another tab to act on the answer. One component mounted four times, never four copies, so they cannot drift apart. A free handle expires after 24h and is renewed from any of them. If you would rather it never expired, buy one on apuchat.com/account (5 USDC) and attach it here with its identity key: the key is checked against Apuchat before it is saved, so a wrong paste fails now instead of presenting as a handle that silently never rings. An attached handle is pushed like a free one: Orquesta registers a webhook on it with its own identity key, so a ring reaches the agent in about a second. Rotating the key on apuchat.com retires that webhook; the poll cron then serves the handle until you attach the new key.

A message to the handle is a prompt, and the answer comes back as a reply. The handle started life as a doorbell: it parsed a ring invite and walked the agent into a video call, and a plain message that was not an invite was read, found uninteresting and dropped — cursor and all, so it was invisible afterwards. From the outside that is indistinguishable from an agent that ignores you. Now anything written to @your-agent runs through the same caller gate as a ring, becomes a prompt on your own machine with the caller’s scopes attached, and its answer is sent back to the sender as a chat message. The Messagessection of the card is the conversation: threads per caller, the agent’s replies marked as its own, a box to write back by hand as the handle, and the messages that were turned away shown in place with the same one-click allow to talk — a refusal you can see is worth more than a silence you cannot. Answers are capped in length and long ones point at the dashboard; one caller can have at most three messages being worked on at a time, so an unattended handle cannot queue unbounded work on somebody’s machine. Two database uniqueness rules do the rest: one record per incoming message, so the webhook and the minute poll cannot both act on it, and one reply per prompt, so the completion hook and the backstop cron cannot both answer.

Who can ring it. The handle is published, and a ring runs a prompt on your own machine — so the signature Apuchat sends proves the message was delivered, never who rang. A new handle is therefore minted restricted: it is an allowlist, and you name the caller @handles that get through and tick, per caller, what they may ask for — talk, read code, run commands, deploy / spend. A third party can be allowed to talk without being allowed to run anything, and nothing said during the call widens that list. For someone whose handle you cannot know in advance, generate a shared passcode — we generate it, you never choose it, and it is shown once at generation because we keep only an encrypted copy. They write passcode: the-code in the ring message and get the scopes you gave the passcode.

Open to anyone is the other setting, and it is a deliberate one: picking it raises a warning and pins every stranger to the narrowest grant there is, talk only, with no way to widen it. A wide grant handed to “anyone” is exactly what that setting cannot be allowed to mean, so the scope pickers are locked rather than merely defaulted. Handles that existed before caller permissions read as open, and the same cap now applies to them. Every ring is logged either way, so a refused caller shows up with an allow to talk shortcut instead of vanishing into a server log.

The chat @mention and the channel list stay read-only here and point at the screen that owns them — a second control for the same field is a second control that can disagree with the first.

Prompt Comments

Every prompt has a comment thread for code review discussion. You can mention team members with @mentions, add feedback on AI-generated code, and discuss changes before merging.

Planning & Specs

The Planning system lets you create structured plans with items that can be converted into prompts or tickets. AI can generate plan breakdowns from high-level descriptions. Structured Specs (bug reports, feature requests, improvements) include acceptance criteria that guide the AI during execution.

Running an item. Hit ▶ on any plan item to send it to the agent as a prompt. The item then shows that prompt's live status and links straight to it, so a plan tracks its own execution instead of just describing it. An item already running can't be dispatched twice; once the prompt finishes, ▶ re-runs it — useful when a run failed.

Board view. Both Planning and Tickets have a list/board toggle in their header. Plans board by item status; Tickets boards by your team's real Linear workflow states — the columns are whatever your team configured, in Linear's own order and colours. Dragging a ticket between columns writes the state back to Linear, and the card rolls back if Linear rejects the move. The board always shows every ticket, so the status tabs step aside while it is open.

Editing a local ticket. Tickets created in Orquesta can be edited, assigned and archived after the fact — the case this is for is a QA pass that files a ticket and then finds out mid-session that it was the wrong title, the wrong type, or that it needs more detail. ✎ opens the ticket's title, type and markdown body, which is exactly what the agent receives when you run it. Assignhands it to any project member. Archive takes it out of the ticket list and the timeline without deleting anything — its logs, comments and cost stay intact, and Archived in the header brings archived tickets back into view to restore them. A ticket the agent is currently running can only be reassigned; edit and archive wait for the run to finish.

Local tickets, with or without Linear. A connected project files local tickets too — the feedback widget writes them there — so the Tickets header carries a Linear / Local switch. The two lists are kept apart on purpose: only Linear issues can be dragged across your team's workflow states, and a merged list would offer actions that work on half the rows.

Local board, sprints and milestones. Local tickets have their own board — Backlog, To Do, In Progress, In Review, Done — and it needs no Linear at all. A card carries two separate states: the run (draft → pending → running → done) and the column somebody dragged it into. A card nobody has touched takes its column from the run, so a ticket that finishes on the agent moves to Done by itself; once you drag it, your column wins and the next run will not yank it back. Group tickets under a sprint or a milestone (the same thing — a sprint is simply one with dates) and the chip above the list shows done/total and the days left, in red once it is past its end date with work still open.

Running tickets. Tick the boxes on one to ten local tickets and the bar offers two ways to run them. A single ticket runs as itself — its own body is the prompt, and the run, its logs and its result stay attached to that ticket, which is what lets the ticket close itself when the run finishes. Run together composes one prompt — the numbered list first so the agent can plan across the whole set, then each ticket's body under its own heading — dispatches it to the agent and moves those cards to In Progress. Send to session builds the same prompt but hands it to the interactive terminal, where it waits in a banner for you to review before anything is sent. Neither one runs a ticket that is already running.

Ticket detail. Clicking a local ticket's title — in the list or on the board — opens it. The left column is the ticket as the agent sees it: the markdown body, the run's result or error, and the comment thread. The right column is everything about it that is not the text: status, assignee and sprint are editable in place, and below them sit who created it and when, when it was last touched, its tags and where it came from. When the ticket has been run, the run block names the engine and model, the branch and commit it landed on, and what it cost. Run, Send to session, Edit and Archive are in the footer, so the panel is enough on its own — you do not have to go back to the list to act on it.

A ticket closes itself. When a run reaches running the ticket moves to In Progress, and when it completes it moves to Done — including from In Review, since a finished run is forward motion. What it will never do is undo a human: a card already in Done or Canceled is never reopened, a card parked in In Review is not dragged back while it runs, and a failed run writes nothing at all so a retry starts from where you left it.

Sprint dates. Creating a sprint starts on today and ends a week out, with 1w / 2w / 1m presets and a running day count beside them, so the common case is one click. The end date cannot precede the start — Create stays disabled while the range is inverted rather than saving a sprint that is already over.

Assisted Mode — QA sends a document, you review a diff

Assisted Mode is for the moment a QA teammate finishes a pass and has a page of findings. Paste the whole document into Assisted on the project page. Orquesta reads it as one document — findings are deduplicated and ordered against each other, not handled one prompt at a time — and sorts every finding into one of four verdicts.

The line it draws is obvious defect vs. product decision, never difficulty. "The Save button does nothing" contradicts its own label, so it runs unattended even if the fix is hard. "We should email the customer when a run finishes" is new behaviour nobody agreed on, so it waits for a human — even though it is trivial to build.

Execute first, review after. This is the difference from auto-evaluate, which blocks a prompt before it runs. Here the reviewer opens a diff that already exists: real files, real line counts, a real commit. Approving an intention and approving a change are not the same review, and only one of them can be done properly.

One run, one branch, one PR. Every item of a run shares a assisted/YYYYMMDD-xxxxxxxx branch and executes strictly one at a time. Auto-deploy is refused for the whole run, server-side — an assisted branch never reaches production on its own, regardless of the project's deployment settings.

The diff gate. Every diff the agent produces is inspected before the next item starts. Migrations, credential-shaped files, deletions, an oversized change, or a claimed fix that changed nothing all halt the run — item N+1 is never stacked on a diff nobody has read. Dependency, CI, auth and binary changes are flagged for the reviewer without stopping the queue. Every flag is shown on the card with the reason it fired.

Who does what. Any project member can start a run — QA has trigger authority, which is the point. Reviewing is separate: it belongs to project owners and admins, plus anyone flagged Assisted reviewer in Team → member permissions. Reviewers get a notification per run and are the only ones who can approve, reject, or queue an escalated finding. Provenance is recorded from the session, not the request body.

“I'll do it” — taking an item yourself. A finding that needs a product decision is often faster to settle in a terminal than to describe. Every card in Needs your call has an I'll do it button: it takes the item, opens an interactive session already on the run's branch, and tells you so in the session header. The serial rule applies to people too — while you hold an item the agent dispatches nothing, so your edits and its edits never land in the same diff. When you end the session your work is committed, pushed and reported, and the item arrives in review with a real diff stat and the same gate flags an agent-produced one would get. Changed your mind? Release puts it back in Needs your call and frees the queue.

Assisted API endpoints:

Batuta AI Orchestrator

Batuta is the AI brain of Orquesta — an intelligent orchestrator that analyzes tasks and routes them to the best execution method. Available on the Max tier ($12/user/mo).

Batuta LLM — Smart Routing

batuta-auto is a synthetic model id. Send your prompt to it and Batuta picks the cheapest model that should still handle the task — Haiku for simple Q&A, Sonnet for day-to-day code, Opus for refactors, architecture and long-context reasoning. You pay only for the upstream tokens actually used, plus the flat subscription. If the model a tier routes to is unavailable (quota cap, auth issue, provider outage), the request automatically cascades to the next model in the fallback chain — no interruption to your workflow.

Why batuta-auto vs picking a model yourself: typical Orquesta users send a mix of trivial prompts ("fix typo") and hard ones ("refactor this auth flow"). Routing the trivial ones to Haiku and only the hard ones to Opus cuts spend 30–60% without dropping quality on the prompts that matter. The routing decision is deterministic given the prompt and exposed in response headers (X-Batuta-Tier, X-Batuta-Routed-To).

Use it from any OpenAI-compatible client (orquesta-cli auto-configures this on first run):

curl https://getorquesta.com/api/v1/chat/completions \
  -H "Authorization: Bearer oclt_YOUR_CLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "batuta-auto",
    "messages": [{"role": "user", "content": "Refactor this React component to use hooks: ..."}]
  }'

Or pin a specific model: claude-opus-4-7, claude-sonnet-4-6, gpt-4o, deepseek-reasoner, grok-4, and GET /api/v1/models for the full list.

Execution Modes

Routines

Routines are saved prompt templates that can be re-executed with one click. Create routines for common tasks like deploying, running tests, checking logs, or performing security scans. Routines can be triggered manually or scheduled.

Scheduled Prompts (Loop)

Schedule prompts to run automatically on a recurring basis via your local agent. Inspired by Claude's /loop command — set a cron schedule and Orquesta dispatches prompts to your agent when they're due.

How it works:

1. Go to your project → Configuration → Scheduled (Loop tab)
2. Create a scheduled prompt with a name, prompt content, and cron schedule
3. The platform checks for due prompts every 2 minutes via a cron endpoint
4. When a prompt is due, it dispatches to your local agent via Supabase Realtime broadcast
5. The agent executes the prompt using Claude CLI and reports results back

Cron presets:

Requirements:

• Your local agent must be running when the schedule triggers
• Maximum 20 scheduled prompts per project
• Max 10 iterations per execution, timeout capped at 1 hour
• Custom cron expressions supported alongside presets

Cloud VMs

Orquesta can provision and manage cloud VMs for your projects, on DigitalOcean or AWS EC2. VMs come pre-configured with security hardening, Docker support, and SSH access.

Providers & sizes

Pick a size and the provider follows from it — DigitalOcean droplets (s-1vcpu-1gb, s-1vcpu-2gb, s-2vcpu-4gb) run in any DigitalOcean region, and AWS instances (t3.micro, t3.small, t3.medium) run in Orquesta's own VPC in us-east-1. The same cloud-init bootstrap, agent install and hardening apply on both. AWS bills compute, storage and the public IPv4 address separately, so a same-RAM AWS instance costs more: droplets run $12–$34/month and AWS instances $17–$49/month, billed monthly through Stripe.

Workspace templates & idle sleep

Set an AWS VM up once — toolchain, checked-out repos, browsers logged in to the accounts your agent uses — then click Save as template. Orquesta captures the disk as a private, encrypted machine image (the VM reboots once, about a minute), and any project in the same organization can then start a new VM from it under Start from. Each clone gets its own agent token and SSH key; everything else is copied, including logged-in sessions, which is why a template can never be launched outside its organization (a partner's child orgs, which the partner owns, are the one exception). The agent on every new AWS VM refuses to start on any machine but its own, so a clone can never run the source project's prompts.

Idle sleep stops a VM after 1 hour to 30 days without prompts; a sleeping VM bills only its disk and the next prompt to the project starts it again. Templates bill only their snapshot storage — up to 10 per organization.

SSH Access

SSH keys are encrypted with AES-256 and stored in Supabase. The platform handles key management, connection setup, and command execution transparently.

# VM access is managed through the dashboard
# SSH keys are auto-generated and encrypted
# Direct SSH (for debugging):
ssh -i /tmp/orquesta-vm-key -o StrictHostKeyChecking=no user@vm-ip

Security Hardening

Every provisioned VM includes:

• UFW firewall (ports 22, 80, 443 only)
• Docker-aware iptables rules (DOCKER-USER chain) — Docker bypasses UFW by default
• Outbound DDoS rate limiting (SYN 50/s, UDP 100/s, ICMP 10/s)
• Malware detection cron (every 5 minutes)
• Restricted sudo for the orquesta user (whitelisted commands only)
• Automatic security patching

On-demand microVM

A project can run with no machine of its own: Orquesta boots an isolated microVM when a prompt arrives, runs the stock agent with orquesta-cli inside it and lets it expire about 15 minutes after the last activity. The model calls go to your organization's own LLM endpoints (Orquesta CLI page) or your Batuta add-on — Orquesta puts no model credential of its own in the microVM. Billing is per minute of microVM lifetime, shown as “Usage (30d)” in Settings → Agents → On-demand runner. Nothing persists between sessions, so the agent must push its work (git, a registry, an API) before the VM is reaped.

• Whole project — tick Start on an Orquesta microVM when creating the project, choose microVM as the hosting option during setup, or turn on the runner in Settings. Every prompt then runs there. It never boots while another agent of the project is online, so prompts cannot run twice.
• Single workstream — on a project that already runs on a local or cloud VM, tick Run on a microVM when creating the workstream, or press Run on microVM on its card (or send run_on_microvm to the workstreams API). Only prompts targeted at that workstream boot the microVM; the rest keep going to the project's own agent. On microVM moves it back to the agent it had before.
• Copy a machine — for a project living on a PC that stays on all day, Copy to microVM in the same Settings section (agent ≥ 0.2.272) makes the online agent push its working tree, uncommitted changes included, to an orquesta/microvm-* branch and send its .env files, which Orquesta stores encrypted and never commits. Untracked files over 5 MB and key-like files (*.pem, id_rsa, .npmrc, credentials) are left out, and only the two newest snapshot branches are kept. Review the branch, env files and install command, then Convert to microVM; every boot restores them and runs the install. Stop the agent on the PC afterwards. Services the PC runs 24/7 do not move.

Integrations

Connect your existing tools to Orquesta for a unified workflow.

Branch + PR Workflow

By default the agent commits and pushes on the project's working branch. If your team reviews changes before they land, open the pull-request button on the connected GitHub card (Configuration → Integrations → GitHub) and turn on New branch + pull request.

• New branch + pull request — the agent cuts a branch off the base branch, pushes there and opens a PR. It never commits to the base branch and never merges the PR itself.
• Branch prefix — feature/ by default, so branches read feature/add-auth.
• Draft PR — open every pull request as a draft.
• Base branch — branches are cut from here and pull requests target it. With the toggle off, it is simply the branch the agent commits to.
• Additional rules — free text appended to the agent's git instructions: commit conventions, reviewers to tag, files to leave alone.

Fix failing CI & reviews on PRs

A pull request opened by an Orquesta prompt does not stop at the first red check. When its CI fails, the project's agent receives the failing logs, fixes the code on the same branch, pushes, and comments on the PR with what it changed — until CI is green or the attempt limit is reached.

• Enable it from Project Settings → Integrations → Fix failing CI on PRs. It installs a webhook on the connected repository, so the GitHub token needs admin rights on the repo. Owners and admins only.
• Only PRs Orquesta opened are touched: a PR whose URL appears in a prompt's output, or whose branch an Auto Agent run created. A PR someone wrote by hand is never acted on.
• GitHub Actions failures (with the tail of each failed job's log) and failures from other CI that uses the Checks API are both supported, each with its own switch.
• Failures that arrive while a fix is still running are folded into one follow-up instead of starting a prompt each, and a failure on a commit that was already superseded by a newer push is ignored.
• After the configured number of attempts per PR (default 3) it stops and says so on the PR; the card has a retry button to give that PR a fresh budget.
• The fix never force-pushes, never pushes to another branch and never opens a new PR. If your working tree has uncommitted changes, the fix runs in a separate git worktree and leaves them alone.
• Fix prompts appear in the dashboard tagged github.

Reviews and @orquesta mentions. Review feedback goes through the same loop:

• Reviews can be Off, Only when @orquesta is mentioned (default) or Every review on tracked PRs. The review body and its inline comments (with file and line) are sent to the agent, which addresses them on the same branch and replies on the PR — or explains why it disagrees.
• Mentioning @orquesta in a review or PR comment also works on PRs Orquesta did not open, and re-arms a PR that ran out of attempts.
• Only people with write access (owner, member or collaborator) are ever acted on. Review bots such as coderabbitai[bot] are ignored unless you list them under Review bots. PRs from forks are ignored.
• Issues (opt-in): an @orquesta comment on an issue opens a new prompt that works on a branch orquesta/issue-N, opens a PR that closes the issue, and replies on the issue with the result. At most 10 issue prompts per hour per project.
• Comments are posted with the connected GitHub account and carry a hidden marker, so Orquesta never reacts to its own comments. After changing the review or issue settings on an existing webhook, use Repair webhook if the card warns that GitHub refused the update.

Vercel

Linear

Telegram Bot

/auth ott_xxxxx    # Authenticate with one-time token\n/prompt Add dark mode  # Submit a prompt\n/status            # Check current execution\n/deploy            # Trigger deployment

Slack

A Slack channel can be pointed at a project. What your team types there becomes a prompt on that project's own agent, and the answer comes back as a threaded reply in the same channel — so the conversation stays where the team already is, and everyone sees both the request and what the agent did about it.

Connecting a channel

1. Install the app — Organization Settings → Slack → Add to Slack, or from a project's Settings → Integrations → Slack. One install covers the whole workspace.
2. Generate a link code in the same card. It is valid for one hour and can be redeemed once.
3. Redeem it in the channel you want linked: /orquesta link ABCD2345.

Both halves are required on purpose. An Orquesta session proves who you are but not that you belong in that channel; a slash command proves you are in the channel but not who you are in Orquesta. Only someone with access to the project can mint a code, and only someone inside the channel can spend it.

Or let Orquesta create the channel

The Slack card also creates a public channel for the project, and that one skips the code entirely: a channel the app creates already has the app inside it, so there is nothing left to prove and the channel is linked the moment it exists. Type a name, see exactly what Slack will call it, create. Owners and admins only — it writes into your workspace, not into Orquesta. The person who creates it and the project's members are invited into it on the spot, matched by their Orquesta email (needs the users:read.email scope); anyone without a Slack account in that workspace is skipped.

This needs the channels:manage scope, which Slack grants at install time. A workspace that installed the app before this existed has to install it again — until then the button reports exactly that. Private channels are not created from here, because that would need a broader scope than the app asks for.

Using it

/orquesta Add a rate limit to the login endpoint   # run a prompt
@Orquesta what changed in the last deploy?        # same thing, as a mention
/orquesta status                                  # which project this channel runs, and what is in flight
/orquesta link CODE                               # link this channel to a project
/orquesta unlink                                  # stop this channel reaching the agent
/orquesta help

• A command typed in the channel opens its own thread and the answer lands there, so long output never floods the channel.
• Mentioning the app inside an existing thread keeps that thread, and the previous few turns are given to the agent as context.
• Prompts from Slack appear in the dashboard tagged slack, with the full log, diff and cost — the Slack reply is a summary, the dashboard is the record.
• At most three prompts run at once per channel; beyond that the app says so instead of queueing silently.
• Every message in and out is kept against the project, so the Slack card shows the recent conversation even for people who are not in the workspace.

Team chat, mirrored with Slack

A team that already lives in Slack does not want a second, half-read inbox inside the dashboard. So choosing Slack merges the two rather than picking one: a message written in the Chat panel is posted into the linked channel, a message written in the channel appears in the panel, and both sides read one conversation. The panel keeps its composer — an earlier release turned it into a pointer at Slack, which cut off everyone who works in the dashboard and split the history in half.

• Organization Settings → Slack sets it for the org, either for every project or for a chosen few, and can pin the policy so no project overrides it. Owners only.
• Project Settings → Integrations → Slack sets it for one project: follow the organization, or disagree with it in either direction.
• Choosing Slack before a channel is linked mirrors nothing — the panel keeps working and shows a reminder, and the two join the moment a channel is linked.
• The mirror is loop-free by construction: each row stores the Slack timestamp of its copy, so our own post coming back as an event, and Slack's up-to-three retries of one delivery, both land on the same unique index and do nothing. Messages from apps and bots are never mirrored in.
• A Slack sender who has no Orquesta account is shown by name without becoming a member: like the agent, they are an author kind, not a profile, so nobody consumes a seat by typing in a channel.
• A thread stays a thread across the bridge — a reply in the Orquesta thread answers in the Slack thread, and the other way round.
• Slack → Orquesta needs the channels:history scope and a message.channels event subscription. A workspace connected before that release keeps working one way and the project's Slack card says so, with the button to reconnect.
• The sidebar says which it is: Integrated next to Team Chat when the chat is mirrored with Slack, Integrate when it is not.
• The Chat page marks each linked project with the Slack mark and lists its channel above the built-in ones, and the project's Slack card links every connected channel — a channel Orquesta created has the app in it, not you, and a public channel you have not joined stays out of your Slack sidebar until you open it and join.
• A project the org policy reaches but that has no channel yet is listed in Organization Settings as no channel · add one, which links straight to that project's Integrations tab — creating or linking the channel happens there, not at org level.

Requests are rejected unless Slack's own signature over the raw body verifies and the timestamp is within five minutes, and each inbound event is recorded once — Slack retries a delivery up to three times, and a retry must not become a second run of the same task. Approval buttons in the thread are the next step and are not in this release.

Derplins

The Hire a prompt specialist chip at the end of a project's tab row opens a short explanation of Derplins — a marketplace of prompt specialists you can hire to work on the project — and links the project in one click (owners and admins). From then on it is listed under Your Orquesta projects on the Derplins dashboard of every project member, with a button to publish a requirement against it, and it is offered first when a Derplins order picks a workspace. Work hired there runs on this project's agent, so every prompt stays here with its full log for audit. The chip's menu opens Derplins or unenrolls the project.

7ots

• Face & voice — Settings → Identity lists your 7ots ots; pick one and the project's resident agent takes its image, meet look and voice. The brain stays the Orquesta agent. On meet video calls the agent appears as the ot itself, in 3D, and speaks in its own voice (agent 0.2.262+). Voice works when the ot is on and its 7ots account is connected to Orquesta — no domain to add.
• Connected ots — Team tab, below AI Agent Tokens: let an outside ot into the project to ask the resident agent questions or hand it work, with per-ot scopes. Every ot shows its own face (the character 7ots renders, or its uploaded picture), not just its name. Owners and admins only.
• Project icon — the sidebar, the project header and the mobile app show the favicon of the project's site, or the GitHub owner's avatar, refreshed when the site or repo URL changes.

Orquesta CLI

AI-powered coding assistant that runs locally with configurable LLM endpoints. Available on the Max tier.

npm install -g orquesta-cli

# Interactive mode
orquesta

# Connect to dashboard
orquesta --token oclt_xxx

# Execute a prompt directly
orquesta -p "Add user authentication"

LLM Configuration

Configure multiple LLM endpoints from the dashboard or locally. Supports:

• OpenAI (GPT-4, GPT-4o, etc.)
• Anthropic (Claude Opus, Sonnet, Haiku)
• Ollama (local models)
• vLLM (self-hosted)
• OpenRouter (model marketplace)
• Any OpenAI-compatible endpoint

Dashboard Sync

LLM configurations sync bidirectionally between the CLI and dashboard. Configure endpoints centrally and distribute to your team. Prompt history is tracked in the dashboard regardless of whether the prompt was submitted via CLI or web UI.

IDE Extension

Connect Cursor, VS Code, or Windsurf directly to Orquesta. Receive prompts from your team's dashboard and execute them inside your IDE — the extension lives in your editor, runs each prompt through a local coding CLI in your workspace, and streams results back to the dashboard in real time.

Installation

Download the .vsix file, then install it in your editor:

# Option 1 — Command palette
# Cursor / VS Code / Windsurf:
# Press Cmd+Shift+P → "Extensions: Install from VSIX..."
# Select the downloaded orquesta-vscode-0.2.12.vsix

# Option 2 — CLI
code --install-extension orquesta-vscode-0.2.12.vsix
cursor --install-extension orquesta-vscode-0.2.12.vsix

Setup & Token

After installation, connect the extension to your project using an agent token:

1. Open your project in Orquesta → Project → Agents
2. Click Create Agent Token → copy the oat_xxx token
3. In your IDE, press Cmd+Shift+P → Orquesta: Set Agent Token
4. Paste the token — the extension connects and opens the sidebar automatically

The token is stored in VS Code's global settings. The extension auto-connects on every startup once a token is saved. To disable auto-connect, set orquesta.autoConnect: false in settings.

Execution Modes

Control how prompts are executed via the orquesta.executionMode setting:

Commands

{
  "orquesta.agentToken": "oat_xxx",       // Your agent token
  "orquesta.autoConnect": true,           // Connect on startup
  "orquesta.workingDirectory": "",        // Defaults to workspace folder
  "orquesta.executionMode": "auto"        // "auto" | "cli" | "ide-ai"
}

Embed SDK

Embed the Orquesta feedback widget in your production applications. Users can report bugs with element inspection, screenshots, and console logs — all flowing back to your Orquesta project.

CDN Setup

The embed SDK is distributed exclusively via CDN — drop two tags into any HTML page and you're done. No build step, no npm install, always the latest version.

<link rel="stylesheet" href="https://getorquesta.com/embed/v1/orquesta.css" />
<script src="https://getorquesta.com/embed/v1/orquesta.min.js"></script>
<script>
  Orquesta.init({
    token: 'YOUR_EMBED_TOKEN',
    position: 'bottom-right'
  });
</script>

New to the embed? Open Project → Embed in the dashboard: a guided checklist walks you through running the agent, setting your target URL, creating a token, and installing the snippet — and a built-in live demo (real widget, mock data) shows what it does before you set anything up. You can also pass demo: true to Orquesta.init() to render the widget with mock data and no backend.

Builder Mode

Builder mode renders a full-screen IDE-style interface (similar to Bolt or Lovable) with three panes: chat on the left, live preview on the right, and a collapsible terminal at the bottom.

<div id="builder-root"></div>
<script src="https://getorquesta.com/embed/v1/orquesta.min.js"></script>
<script>
  Orquesta.init({
    token: 'YOUR_EMBED_TOKEN',
    mode: 'builder',
    container: '#builder-root',
    previewUrl: 'https://your-app.com'
  });
</script>

Builder panes:

• Chat — Send prompts, see AI responses and status updates
• Preview — Live iframe with URL bar and refresh button, auto-reloads on prompt completion
• Terminal — Real-time execution logs, collapsible, color-coded output

Panes are resizable via drag handles. The terminal can be collapsed/expanded. Fully responsive with a stacked layout on mobile.

Prompts sent from the embed ship by default. Because the sender is looking at the deployed site, every embed prompt asks the agent to commit, push, deploy and report the commit SHA once the code change is done — then the preview reloads with a cache-busting parameter so the new version is actually fetched. Set auto_deploy: false on the embed token settings to opt a token out.

Features

• Element Inspector — Click any element to mark it in a bug report
• Console Capture — Automatically captures browser console output
• Network Capture — Records failed API requests
• Comment System — Inline feedback on specific elements
• Timeline — User action timeline for reproduction

Browser Extension

The embed needs a <script> tag in the page, so it only reaches sites you control. The Orquesta browser extension does the same job from the browser side: it injects the widget into any page with no HTML change, and it lets Orquesta CLI drive the browser you are already signed into.

• Inject the embed anywhere — a client's site, a staging box behind SSO, production. Prompts land in the project the embed token belongs to.
• Your real browser — the browser_ext_* tools use your actual profile and sessions, unlike browser_*, which launches a clean, logged-out Chrome.
• Console and network capture — read what the page logged and what it requested, from the CLI.
• Side-panel chat (0.3.0) — click the toolbar icon, sign in with Orquesta, and chat with an agent that reads and operates the current tab (click, fill, navigate, read console/network). Runs on Batuta; no CLI or bridge needed.
• Send to project (0.3.0) — select text on any page, right-click Send to Orquesta project, pick the project and it runs as a prompt on that project's agent. The panel streams its log and has a Stop button (POST /api/v1/prompts/{id}/cancel).

Chrome and Edge. Firefox is not supported (the extension uses the Chrome DevTools Protocol).

Install & Pair

The extension is not on the Chrome Web Store yet, so it is loaded unpacked from the orquesta-extension repository. Three pieces, all local:

# 1. build the extension
git clone https://github.com/Getorquesta/orquesta-extension
cd orquesta-extension
npm install
npm run build

# 2. load packages/extension/build unpacked from chrome://extensions
#    (enable Developer mode first)

# 3. in orquesta-cli: /tool -> Browser Extension (your own browser)

Enabling the tool group starts the local bridge for you — a small daemon on 127.0.0.1 that the extension talks to. Click Pair in the extension popup, ask the CLI for the code (browser_ext_status reports it), and the browser is connected.

Pairing survives restarts, so this happens once per browser, not once per session. The bridge outlives the CLI on purpose: short orquesta -p runs and several sessions share one browser without pairing again. Run it yourself with npx orquesta-bridge if you would rather see its log.

CLI Tools

In Orquesta CLI, run /tool and enable Browser Extension (your own browser). That registers:

• browser_ext_status — is the bridge up, is a browser paired
• browser_ext_tabs / _open / _reload — list tabs, open a URL, reload
• browser_ext_click / _fill / _press / _select — interact with the page
• browser_ext_text / _html / _eval — read the page, run JS in it
• browser_ext_screenshot — capture the visible tab
• browser_ext_console / _network — console messages and requests
• browser_ext_wait — wait for a selector or a navigation
• browser_ext_embed — inject the Orquesta widget into the page

Security

• Nothing leaves the machine. The CLI talks to the bridge over loopback and the bridge talks to the extension over a paired local WebSocket. There is no Orquesta server in the path.
• Pairing is explicit and expires. The bridge prints a code valid for two minutes; the extension only connects after you type it.
• The control token is a file, not an argument. It is written 0600 under ~/.orquesta-cli/, so it never appears in ps.
• The bridge binds 127.0.0.1 only and rejects browser-originated requests, so a web page cannot reach it through DNS rebinding.

Remote Desktop

Beyond driving a browser, the agent can operate the whole desktop of the machine it runs on — moving the mouse, typing, and taking screenshots — and you can take over live from the dashboard. This is for automating flows in native apps, not just web pages. Currently Linux/X11; Windows and macOS are coming.

Enable & modes

Off by default. Turn it on per project in Settings → Agent → Remote Desktop. Three modes:

• Automation — the agent controls the desktop programmatically (no VNC server started).
• Live (VNC) — a human takes over from the dashboard viewer.
• Both — automation plus live take-over.

Using the viewer

Open the Remote Desktop tab on a project. The screen appears as soon as the agent starts streaming; watching needs nothing beyond project access.

• Take control hands your mouse and keyboard to the remote machine. Moves, clicks, drags, scroll wheel and middle/right click all travel; typing goes to whatever has focus over there.
• Pop out opens the desktop in its own window, so it can sit on a second monitor while you keep working in the project tab.
• Disconnect leaves the session. The agent stops capturing the screen entirely once nobody is watching, which is also what the viewer count next to the status tells you.
• Session history lists every time someone opened this desktop, for how long, and whether they took control.

Pairing PIN

An owner or admin can set a PIN in Settings → Agent → Remote Desktop. It gates taking control, not watching: seeing a screen you already have dashboard access to is not the dangerous capability — driving the machine is. The PIN is stored hashed and checked by the relay, so neither the browser nor the agent can be talked out of it.

Security

• Opt-in, off by default. Full desktop control is high-risk, so nothing runs until you enable it for a project.
• Watching and driving are separate permissions. Control is granted per session and dies with it — reconnecting asks again, and the PIN (if set) is asked again too.
• The VNC server binds localhost only. The only path in is the agent's authenticated WebSocket tunnel — never exposed to the network.
• Disabled under sandbox Strict. Strict filesystem isolation and full desktop takeover are mutually exclusive; the agent refuses to enable it.
• Idle sessions are reaped so an abandoned take-over does not leave the desktop reachable.

MCP Server

Orquesta speaks the Model Context Protocol at a single endpoint, so an assistant running anywhere — Lovable, ChatGPT, Claude Code, Cursor, VS Code — can read a project's history and write its own work back into it. Nothing to install: the hooks above need a process on your machine, while MCP reaches tools that run in the cloud.

https://getorquesta.com/api/mcp

The transport is stateless: each call is one HTTPS request, there is no session to keep alive and no event stream to hold open.

Connecting a client

Paste the URL. A hosted client discovers the OAuth server from the 401, registers itself, and sends you to an Orquesta consent screen where you pick the organization to expose — no API key is created, shown, or copied. In Lovable: Dashboard → Connectors → search mcp → New MCP server, paste the URL, leave Authentication on OAuth, then Add server. ChatGPT and Claude ask for the URL alone.

Each teammate authorizes with their own account, and the token reaches exactly the projects that person can already see. Every connected tool appears under Settings → Connections with how many sessions it has recorded, when it last did something, and how many people authorized it — one button there disconnects it for the whole organization.

From the terminal, orquesta-cli is an MCP client too, and it now does OAuth: orquesta mcp login <name> opens the browser once and keeps a refreshing token on that machine, which is the only way to reach a server that issues no API key. orquesta mcp list marks an authorized server, and orquesta mcp logout <name> forgets it.

Clients with no OAuth support take a bearer token instead — an organization API key (oak_) from Settings → API Keys, keeping the prompts:write scope if the client should be able to record its work:

claude mcp add --transport http orquesta https://getorquesta.com/api/mcp \
  --header "Authorization: Bearer oak_abc123..."

{
  "mcpServers": {
    "orquesta": {
      "url": "https://getorquesta.com/api/mcp",
      "headers": { "Authorization": "Bearer oak_abc123..." }
    }
  }
}

Tools

External Agents API

REST API that lets third-party AI agents (GPT, LangChain, CrewAI, custom agents) connect to your Orquesta project. The external agent brings the brain, Orquesta provides execution + coordination.

How it works:

1. Generate an oxa_ token from the dashboard (Project → Team → External Agents)
2. Register your agent via the API
3. Read project context to understand the codebase
4. Submit prompts — the local orquesta-agent executes them
5. Poll for results and iterate

Authentication

All API requests require a Bearer token with appropriate scopes:

Authorization: Bearer oxa_abc123...

Rate limits: 30 requests/minute, 300 requests/hour (configurable per token).

The two *:write scopes are off by default when a token is created and must be ticked explicitly. They let a deploy agent feed one project its variables and files without holding an org-wide oclt_ token that acts as the whole user. They are strictly write-only: the same token gets 403 on GET/DELETE of those routes, and every write is recorded in the token's activity log (keys and file names only, never values).

API Reference

Base URL: https://getorquesta.com/api/external-agent

Examples

import requests

API = "https://getorquesta.com/api/external-agent"
TOKEN = "oxa_your_token_here"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

# 1. Register your agent
requests.post(f"{API}/register", headers=HEADERS, json={
    "name": "my-gpt-agent",
    "model": "gpt-4o",
    "provider": "openai",
    "version": "1.0.0",
    "capabilities": ["code-review", "testing"]
})

# 2. Read project context
ctx = requests.get(f"{API}/context", headers=HEADERS).json()
print(ctx["memory"])  # Project knowledge

# 3. Submit a prompt
resp = requests.post(f"{API}/prompts", headers=HEADERS, json={
    "content": "Add input validation to the signup form",
    "tags": ["feature"]
})
prompt_id = resp.json()["promptId"]

# 4. Poll for completion
import time
while True:
    status = requests.get(
        f"{API}/prompts/{prompt_id}", headers=HEADERS
    ).json()
    if status["status"] in ("completed", "failed"):
        print(f"Result: {status['result']}")
        break
    time.sleep(5)

curl -X POST https://getorquesta.com/api/external-agent/prompts \
  -H "Authorization: Bearer oxa_xxx" \
  -H "Content-Type: application/json" \
  -d '{"content": "Fix the login bug", "tags": ["bug"]}'

Autonomous Agent Bot

Orquesta ships with a built-in autonomous bot that uses Claude CLI as its brain to strategically plan and submit tasks via the External Agents API. The local agent executes each task.

No API key needed — the bot uses your Claude web subscription via claude login.

How it works:

1. Registers as an autonomous agent via the API
2. Gathers project context, recent prompts, and queue status
3. Spawns claude -p with full context to decide the next task
4. Submits the prompt, polls until completion, records the result
5. Repeats — each iteration builds on the previous results

# Run with token (default 5 iterations)
npx tsx scripts/autonomous-agent/run.ts oxa_your_token

# Or use env var with custom iterations
MAX_ITERATIONS=10 ORQUESTA_AGENT_TOKEN=oxa_xxx npx tsx scripts/autonomous-agent/run.ts

Configurable: MAX_ITERATIONS (default 5), ITERATION_DELAY (default 30s between iterations).

Security

Security is foundational to Orquesta. Your code runs on your machine, credentials are encrypted, and all data access is controlled by row-level security policies.

Row-Level Security

Every Supabase table has RLS policies enforcing organization-level isolation. Users can only access data within their organization. Admin operations use a service role key with elevated permissions, never exposed to the client.

Token Management

All tokens are SHA-256 hashed before storage. Only the hash is stored — the plain token is shown once at creation and cannot be retrieved. Tokens can be revoked instantly from the dashboard.

Environment Variables & Secret Files

Project secrets live in Settings → Environment Variables and are injected into every prompt the agent runs. Two kinds: key/value variables, and secret files — a signing key, keystore, service-account JSON or.p8 that must exist on disk. The agent writes each file to its destination path (relative to the project, absolute, or ~/…; mode 0600) right before the run and exports ORQUESTA_FILE_<NAME> with the resolved path.

• Paste .env — both the setup wizard and Settings accept a pasted .env (comments, quotes and export prefixes handled; existing keys are updated in place).
• API access with a CLI token — /api/projects/{id}/env, /credentials and /secret-files accept Authorization: Bearer oclt_… as well as the dashboard session, so scripts and agents can load secrets without a browser. Deleting requires the credentials:manage permission.
• Write-only access with an external-agent token — an oxa_ token minted with the opt-in env:write / secret-files:write scopes (unticked by default) can POST to /env and /secret-files for its own project only. It cannot read or delete them, and each write is logged in the token's activity feed. Prefer this over an oclt_ for an agent whose only job is to load secrets — see External Agent scopes.
• Token health — orquesta --status now verifies the stored CLI token with the server and warns when it is revoked, expired, or an old token with no associated user (those are refused with 403 on every write). orquesta --login mints a fresh one.
• Up to 32 files, 512 KB each, 4 MB total per project. Stored encrypted like every other credential.

# Merge variables from a .env file (existing keys are updated, others kept)
curl -s -X POST https://getorquesta.com/api/projects/$PROJECT_ID/env \
  -H "Authorization: Bearer $ORQUESTA_CLI_TOKEN" -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile dotenv .env.production '{dotenv: $dotenv, merge: true}')"

# Upload a signing key as a secret file
curl -s -X POST https://getorquesta.com/api/projects/$PROJECT_ID/secret-files \
  -H "Authorization: Bearer $ORQUESTA_CLI_TOKEN" -H "Content-Type: application/json" \
  -d "$(jq -n --arg b64 "$(base64 -w0 AuthKey.p8)" \
        '{files:[{name:"APPLE_AUTH_KEY", path:"~/.private_keys/AuthKey.p8", contentBase64:$b64}]}')"

# In the prompt the agent runs, the file is already on disk:
#   eas build --non-interactive   # reads $ORQUESTA_FILE_APPLE_AUTH_KEY via your eas.json / env

Identity Verification (Passkey / OTP)

An organization or project can require a second identity check, on top of the normal login, before anyone makes its agent act: sending or running prompts, interactive sessions, browser control, remote-desktop control, scheduled runs and auto-agent autonomy. Members verify with a passkey (Touch ID, Windows Hello, a security key) or an authenticator app code.

• Turn it on in Organization Settings → Identity verification for agents (owner), or per project in Settings → Agent (owners and admins). A project can only make the policy stricter.
• It expires after the configured time (15 min to 24 h, default 8 h; the shorter of org and project wins), when you sign out, or when you press Lock now in your profile.
• Enroll in Profile → Identity verification, or directly from the prompt the first time it is needed. Adding or removing a method after the first one asks you to verify again, and every change is emailed to you.
• Relaxing the policy (turning it off or lengthening the expiry) needs a verification from the last 15 minutes, so a stolen session cannot switch it off.
• Scope: the check applies to dashboard sessions. Token-authenticated paths (public API, CLI, Slack, Telegram, external agents) are governed by their tokens.

Security Scanning

Built-in security scanning analyzes prompts and generated code for vulnerabilities. Scans detect common issues like SQL injection, XSS, command injection, and exposed credentials. Results appear in the Security panel with severity ratings and remediation guidance.

GuardRails

GuardRails is a per-project prompt protection layer that intercepts every prompt before it reaches the agent. It scans for prompt injection, jailbreaks, role overrides, and data exfiltration attempts using 30+ built-in regex rules plus an optional GPT-4o-mini AI review pass.

How it works:

1. Every prompt is scored against 6 rule categories before execution
2. Score ≥ 70 → blocked, 30–69 → warned, < 30 → passed
3. Result is stored on the prompt (guardrail_status, guardrail_flags)
4. In block mode the prompt is cancelled and a 403 is returned; in warn mode it runs but is flagged

Action Modes:

• Block — prompt is cancelled; the sender receives an error with the matched rule
• Warn — prompt executes normally but is flagged in the violations log
• Log Only — prompt executes, violations recorded silently for auditing

Configuration: Go to Agent → GuardRails in the project dashboard to enable, set the mode, toggle AI review, and add custom regex patterns. Project admins can also toggle GuardRails on/off directly from the Send Prompt toolbar using the GuardRails button — no need to navigate away.

GuardRail API endpoints:

Quality Gates

Quality Gates let admins require a Simulate before Submit step for specific team members. When enabled, the member's Execute button changes to Simulate — clicking it calls an AI that previews what the agent would do (files touched, commands run, risks). The member then chooses Sign & Submit to proceed or Cancel.

How to enable:

1. Go to Team in the project dashboard
2. Click the Sign-off badge next to a member's name (admins only)
3. The badge turns amber when active — that member will see "Simulate" instead of "Execute"
4. The simulation is tracked via quality_gate_signed on the prompt record

CLAUDE.md Sync

Edit your project's CLAUDE.md directly from the dashboard and keep it in sync with the agent's working directory. Claude Code reads CLAUDE.md from the project root on every session — no more manual SSH to update it.

Dashboard Editor

Open Configuration → Settings → CLAUDE.md tab. Edit the content and save. It is stored in projects.settings.claude_md. On the next agent connect, the file is written to <workingDirectory>/CLAUDE.md.

Agent Sync

On first connect the agent uploads the local CLAUDE.md to the dashboard (only if no user content is saved):

1. Agent reads CLAUDE.md from its working directory
2. POSTs content to /api/agent/claude-md
3. Server stores it only if settings.claude_md is not yet set (user edits are never overwritten)
4. On subsequent connects, if settings.claude_md is set, it is written back to disk

Organization Agent Context

CLAUDE.md is per project. Rules that hold for every project of the organization live in Settings → Agent context (/dashboard/settings, owners only) — policy you should never have to restate: “always work on a branch and open a PR”, “ask before adding a dependency”, “write commit messages in English”.

It is delivered after the project instructions and after the integration skills, under a header stating it overrides them — prompt precedence is positional, so the last labelled block wins. Running agents reload it within seconds of saving.

Code Browser

The Code Browser tab provides a read-only view of your project's source code directly from the dashboard. Files are fetched from GitHub or via SSH — no local clone required.

Features:

• Syntax highlighting for 20+ languages (TypeScript, Python, Go, Rust, SQL, HTML, CSS, and more)
• File explorer with search filtering and directory navigation
• In-file search with match navigation (Ctrl+F or search button)
• Breadcrumb path navigation and file metadata (size, line count, language)
• Copy full file content to clipboard
• Ask AI — open a side panel to ask questions about the file you're viewing. Streaming responses powered by Claude Haiku or GPT-4o-mini

This is a view-only experience — files cannot be modified, created, or deleted from the Code Browser. Use it for code reviews, onboarding new team members, or exploring unfamiliar parts of the codebase.

Ask AI

Click the Ask button in the file toolbar to open the AI panel. The AI receives the file content as context and can answer questions about the code, explain patterns, identify potential issues, and describe what functions do. Suggested prompts are provided to get started.

Performance Dashboard

The Performance tab (Configuration → Performance) shows aggregated token usage and cost data for the project, broken down by model and day. Data comes from the tokens_used and cost_cents fields populated by the Claude CLI executor.

What you see:

• Stat cards: Total cost ($), Total tokens, Prompt count
• Daily bar chart: cost per day over the selected period
• Model breakdown table: model, provider, prompts, tokens, cost — sorted by cost
• Spend by member: per-user token + cost spend, sorted by usage, with a High-spend flag when one member concentrates more than 40% of the team's tokens
• Per-user token limit: org owners/admins can set an org-wide monthly Batuta token cap per member, in either alert-only mode (members & admins are emailed at 80% / 95%) or block mode (prompts are rejected past the cap until next month)
• Period selector: 7 days / 30 days / All time

Performance API

Quick Prompts

Quick Prompts let you save frequently used prompts as reusable templates. Instead of retyping the same instructions, save them once and execute with a single click.

Create & Use Quick Prompts

Creating:

• Open the prompt input in any project
• Type your prompt, then click the Save as Quick Prompt button
• Give it a name and optional description
• Quick prompts are saved per-project in the quick_prompts table

Using:

• Click the Quick Prompts dropdown in the prompt input area
• Select a saved prompt to auto-fill the input
• Edit if needed, then submit as normal

Use cases:

• Standard code review prompts
• Deployment checklists
• Bug report templates
• Recurring maintenance tasks

Building in Public

Make your project's AI activity publicly visible — no login required. Enable the "Build in Public" toggle and your project appears on the Live Feed at getorquesta.com/feed, letting anyone follow along as your AI agent ships code in real time. A great way to generate FOMO and showcase what AI-powered development looks like.

Enable & Configure

Go to Project → Settings → Permissions tab. Under "Build in Public", flip the toggle on.

• Custom slug — Set a short URL like my-project so your feed page lives at getorquesta.com/feed/my-project instead of a UUID. Must be lowercase letters, numbers, and hyphens (3–50 chars). Must be unique.
• Live site URL — Enter your deployed app URL (e.g. https://myapp.com). Visitors on your feed page will see an embedded iframe preview of the actual running product beneath the prompt timeline.

Live Feed

The global feed at /feed lists all public projects, sorted by community vote score. Each card shows:

• Agent online/offline status (green dot = seen in the last 3 minutes)
• Amber "Running now" pulse when a prompt is actively executing
• Last 3 prompt snippets with status icons and source badges (Web / Telegram / Auto / etc.)
• Up/down vote buttons — score is upvotes minus downvotes, stored per anonymous browser UUID
• Link to the full project timeline at /feed/[slug]

The project detail page (/feed/[slug]) shows:

• Iframe preview of the live site (if a site URL is configured)
• Full prompt timeline (last 50 prompts, read-only)
• Expandable prompt content, tags, source, duration
• Share on X button and copy-link button
• Live logs terminal for any currently running prompt

Real-time Logs

When a prompt is running, a terminal panel appears below it on the public project page and streams agent logs every 2 seconds. Logs are filtered — internal thinking entries are hidden, and only actionable output is shown:

Logs are capped at the last 80 entries per poll and truncated to 500 chars per line. Auto-scrolls to the latest entry.

Public API

These endpoints require no authentication — they are fully public:

API Keys

API keys (oak_) give external integrations access to Orquesta data. Generate them at Settings > API Keys, where each key carries two independent restrictions: which scopes it holds (read-only by default) and which projects it may reach (all of them, or a chosen few). Both are editable afterwards without re-issuing the token.

Authentication

Include your API key in every request:

# Option 1: Authorization header
curl -H "Authorization: Bearer oak_xxx" https://getorquesta.com/api/v1/projects

# Option 2: X-API-Key header
curl -H "X-API-Key: oak_xxx" https://getorquesta.com/api/v1/projects

Endpoints

Projects & VMs

Org keys (oak_ only — CLI, agent and MCP tokens are refused) can create projects and manage each project's cloud VM. Writes require that the user who created the key is still an owner or admin of the organization. Limit: 30 requests/minute, 300/hour per key. VM responses never include the SSH private key or the agent token.

Partner organizations (enabled by Orquesta) can create one child organization per end-customer and act on it by sending X-Orquesta-Org: <child id> to any endpoint above. A child with Stripe billing must pay through its checkout first; until then creating a VM answers 402 with code: billing_required.

Scopes

A key holds only the scopes you tick. A request outside them answers 403 naming the missing scope.

Two presets cover most cases: Read only (every :read scope except the opt-in vms:read) and Read + submit prompts. Creating a key without naming any scope yields a read-only key. The infrastructure scopes are never in a preset: tick them explicitly.

Project restriction

A key is org-wide unless you restrict it. When you pick projects, every endpoint — REST and MCP — is filtered to them: listings return only those projects' rows, and asking for anything else answers 404, the same answer as a project that does not exist, so a key cannot probe which project ids are real. Existing keys stay org-wide until you edit them.

# A key restricted to one project
curl -H "Authorization: Bearer oak_xxx" \
  "https://getorquesta.com/api/v1/prompts?projectId=<allowed>"   # 200

curl -H "Authorization: Bearer oak_xxx" \
  "https://getorquesta.com/api/v1/prompts?projectId=<other>"     # 404

OSS Community

Orquesta OSS is a self-hosted, open-source version of the platform. OSS instances can optionally publish themselves to the getorquesta.com/feed community feed, making your instance discoverable by other developers.

Self-Hosting

Get started with the OSS version:

# Clone the repository
git clone https://github.com/Orquesta-live/orquesta-oss.git
cd orquesta-oss

# Install dependencies
npm install

# Set up the database
npx prisma db push

# Start the development server
npm run dev

OSS Stack:

• Next.js 15 + Prisma + SQLite (no external DB needed)
• Better Auth for authentication
• Socket.io for real-time agent communication
• Full Agent Grid, agent tokens, and interactive sessions

Publish to Community Feed

OSS instance owners can publish their instance to the community feed at getorquesta.com/feed. This makes your instance visible to the community.

How to publish:

• Open your OSS instance dashboard
• Click the Publish to Community button in the project header (owner only)
• Your instance details are sent to POST /api/oss/publish
• Your instance appears in the Community section of /feed

API:

Billing & Plans

Feature Matrix

Batuta LLM Add-on

Batuta LLM is a managed LLM proxy that gives your team access to all major AI models (GPT-4o, Claude, Gemini, DeepSeek, Mistral, Grok) without managing API keys. Use it from the dashboard chat or through Orquesta CLI.

Batuta Standard is included with the Max plan — Max orgs automatically get the 5M token/mo quota and don't need the add-on. The Plus, Pro, and Team tiers below let you scale further.

Enterprise

Orquesta Enterprise is designed for organizations that need advanced security, compliance, and control over AI-powered development workflows. From SSO and fine-grained permissions to on-premise deployment and SOC 2 compliance, Enterprise gives your security and procurement teams everything they need to approve Orquesta for production use.

SSO & Identity Management

Orquesta integrates with your existing identity provider so your team can log in with their corporate credentials. No separate passwords, no manual user provisioning.

SCIM Provisioning

Automate user lifecycle management with SCIM 2.0. When employees join or leave your organization, their Orquesta access is automatically provisioned or revoked through your identity provider.

• Automatic user creation when added to IdP group
• Automatic deactivation when removed from IdP
• Group-to-role mapping (IdP groups map to Orquesta roles)
• Just-in-time (JIT) provisioning for first-time logins

Multi-Factor Authentication (MFA)

Enforce MFA at the organization level. Orquesta supports TOTP (authenticator apps), WebAuthn (hardware keys like YubiKey), and SMS as a fallback. Admins can require MFA for all members or specific roles.

Domain Verification

Claim your email domain (e.g., @yourcompany.com) so that any employee who signs up with that domain is automatically added to your organization. Prevents shadow accounts and ensures centralized management.

Advanced Roles & Permissions

Enterprise RBAC goes beyond the standard Admin / Developer / Viewer roles. Create custom roles with granular permissions scoped to specific projects, environments, and actions.

Built-in Enterprise Roles

Custom Roles

Create custom roles with fine-grained permission sets. Each permission is a combination of resource + action:

{
  "name": "Senior Developer",
  "permissions": [
    "prompts:submit",
    "prompts:execute",
    "prompts:approve",
    "logs:read",
    "git:commit",
    "git:push",
    "agents:connect",
    "agents:interactive_session",
    "vm:ssh",
    "settings:claude_md:edit"
  ],
  "restrictions": {
    "environments": ["development", "staging"],
    "max_tokens_per_prompt": 50000,
    "blocked_commands": ["rm -rf /", "DROP DATABASE", "format"]
  }
}

Environment-Scoped Access

Restrict what environments each role can target. A developer might have full access to development and staging but require approval for production. Environments are defined per project and enforced at the agent level.

• Development — open access, no approvals required
• Staging — developer access, optional review
• Production — requires quality gate approval from Reviewer or Project Admin
• Restricted — only Org Admins and Security Officers, full audit on every action

Command Allowlists & Blocklists

Define which shell commands and patterns are allowed or blocked per role and environment. The agent enforces these rules before execution, preventing destructive or unauthorized operations.

{
  "production": {
    "blocked_patterns": [
      "rm -rf",
      "DROP TABLE",
      "DROP DATABASE",
      "truncate",
      "format",
      "mkfs",
      "dd if=",
      "> /dev/sd"
    ],
    "require_approval": [
      "git push",
      "npm publish",
      "docker build",
      "kubectl apply",
      "terraform apply"
    ]
  }
}

IP Allowlisting

Restrict dashboard and API access to specific IP ranges. Only requests from your corporate network, VPN, or approved CIDR blocks can access Orquesta. Configured at the organization level.

{
  "ip_allowlist": {
    "enabled": true,
    "ranges": [
      "203.0.113.0/24",
      "198.51.100.0/24",
      "10.0.0.0/8"
    ],
    "bypass_for_sso": false,
    "enforce_on_api": true,
    "enforce_on_agents": true
  }
}

Deployment Options

Choose the deployment model that matches your security and compliance requirements. Orquesta supports everything from fully-managed cloud to air-gapped on-premise installations.

Data Residency

Choose where your data is stored to comply with regional regulations. Available regions for managed cloud and VPC deployments:

• US East (Virginia) — default
• US West (Oregon)
• EU West (Frankfurt) — GDPR-compliant
• EU North (Stockholm)
• LATAM (Sao Paulo)
• APAC (Sydney, Tokyo)

High Availability Architecture

Enterprise deployments run in a high-availability configuration with automatic failover:

• Multi-AZ database replication with automatic failover
• Load-balanced API servers across availability zones
• WebSocket relay with sticky sessions and reconnection handling
• Redis cluster for real-time state and caching
• Automated daily backups with 30-day retention (configurable)
• Disaster recovery with RPO < 1 hour, RTO < 4 hours

Audit & Governance

Every action in Orquesta is logged with full context. Enterprise audit goes beyond standard logging with immutable audit trails, SIEM integration, and configurable retention policies.

Immutable Audit Log

Every event is written to an append-only audit log that cannot be modified or deleted, even by Org Owners. Events are cryptographically chained to detect tampering.

SIEM Integration

Stream audit events in real-time to your SIEM or log management platform. Supported targets:

• Splunk — via HEC (HTTP Event Collector)
• Datadog — via Log Forwarding API
• Elastic / ELK — via Elasticsearch bulk API
• AWS CloudWatch — for VPC deployments
• Azure Monitor — via Log Analytics workspace
• Custom Webhook — any HTTPS endpoint, JSON payload, HMAC-signed

Approval Workflows

Enterprise quality gates support multi-level approval chains. Configure approval requirements per environment and action type:

{
  "approval_policy": {
    "production": {
      "prompt_execution": {
        "required_approvals": 2,
        "approver_roles": ["Reviewer", "Project Admin"],
        "auto_reject_after_hours": 48,
        "require_diff_review": true
      },
      "git_push": {
        "required_approvals": 1,
        "approver_roles": ["Project Admin", "Org Admin"]
      },
      "destructive_commands": {
        "required_approvals": 2,
        "approver_roles": ["Org Admin", "Security Officer"],
        "notify": ["#security-alerts"]
      }
    },
    "staging": {
      "prompt_execution": {
        "required_approvals": 1,
        "approver_roles": ["Reviewer", "Developer"],
        "auto_approve_after_hours": 24
      }
    }
  }
}

Data Retention Policies

Configure how long different types of data are retained. Meet regulatory requirements while managing storage costs:

• Audit logs — 1 year minimum, configurable up to 7 years (required for SOC 2, HIPAA)
• Execution logs — 90 days default, configurable
• Prompt history — 1 year default, configurable
• Git diffs — retained indefinitely (linked to commits)
• Session recordings — 30 days default, configurable
• Automated purge — data is securely deleted after retention period expires

Cost Management & Budgets

Enterprise cost management gives finance and engineering leaders full visibility and control over AI spending across the organization.

Budget Controls

Usage Dashboard

A dedicated enterprise analytics dashboard provides:

• Real-time token usage across all projects and teams
• Cost breakdown by project, user, team, and environment
• Historical trend analysis with monthly/quarterly reports
• Export to CSV/PDF for finance reporting
• API cost attribution (which LLM provider, model, and tier)
• Forecasting based on usage trends

Enterprise Integrations

Connect Orquesta to the tools your team already uses. Enterprise integrations go beyond standard webhooks with deep, bidirectional integrations.

Webhook System

The enterprise webhook system supports any HTTPS endpoint with configurable events, retry policies, and HMAC signature verification:

{
  "url": "https://your-service.com/webhooks/orquesta",
  "secret": "whsec_...",
  "events": [
    "prompt.submitted",
    "prompt.approved",
    "prompt.executed",
    "prompt.failed",
    "agent.connected",
    "agent.disconnected",
    "security.alert",
    "budget.threshold"
  ],
  "retry_policy": {
    "max_retries": 5,
    "backoff": "exponential",
    "timeout_ms": 30000
  },
  "headers": {
    "X-Custom-Header": "value"
  }
}

SLA & Support Tiers

Enterprise customers receive premium support with guaranteed response times and a dedicated customer success team.

Slack Connect

Enterprise customers get a shared Slack Connect channel with Orquesta engineering. Get direct access to the team that builds the product for fast issue resolution, feature requests, and architectural guidance.

Compliance & Certifications

Orquesta is committed to meeting the highest security and compliance standards. Below is our current compliance posture and certification roadmap.

Current Compliance

Certification Roadmap

The following certifications are planned or in progress as part of our enterprise compliance roadmap:

Security Practices

• Penetration Testing — Annual third-party pentest. Results available under NDA.
• Bug Bounty Program — Responsible disclosure program for security researchers.
• Dependency Scanning — Automated CVE scanning on every build via Snyk/Dependabot.
• Static Analysis — SAST tooling integrated into CI/CD pipeline.
• Secret Detection — Pre-commit hooks and CI checks prevent secret leakage.
• Employee Security — Background checks, security training, least-privilege access, hardware keys for infrastructure.
• Incident Response — Documented IR plan with 1-hour acknowledgment for P1 incidents. Postmortem within 72 hours.
• Vendor Management — All sub-processors evaluated for security posture. DPAs in place with all vendors.

Trust Center

Visit getorquesta.com/trust for our public Trust Center, which includes:

• Real-time system status and uptime history
• Security whitepaper (downloadable PDF)
• SOC 2 report request form
• DPA (Data Processing Agreement) template
• Sub-processor list
• Penetration test summary
• Responsible disclosure / bug bounty policy

Enterprise Onboarding

Every enterprise customer receives a structured onboarding experience to ensure fast time-to-value and successful adoption across teams.

Onboarding Timeline

Enterprise Evaluation

We offer a 30-day enterprise pilot with full feature access. The pilot includes:

• Full Enterprise feature set (SSO, RBAC, audit, integrations)
• Up to 25 users during the pilot period
• Dedicated Slack Connect channel with Orquesta team
• Two 1-hour onboarding sessions
• Security questionnaire pre-filled
• Custom proof-of-concept for your specific workflow