Introducing a new way to review your PRs.

Read the announcement

stablyai / orca

Orca lets you run a fleet of bots with your own subscription (e.g. Claude Code, Grok, Agy, Codex). Available on desktop, mobile and remote runtime.

View on GitHub

34 documents · Updated Nov 20, 2026

docs / bot-orchestration

Bot orchestration

Bot orchestration is the bot platform that gives each bot a lasting identity and coordinates conversations, shared work, connector access, work items, background runs, sharing, and agent execution. A desktop host owns the durable bot state and work context. Cloud services connect approved external systems, while desktop and mobile clients present the same host-scoped activity.

System model

Persistent bot identity

A bot is a named worker with a stable record, a private home, a selected agent, and a home workspace. Its home holds its instructions and memory. The record connects that home to conversations, connector access, work preferences, and client state. This lets the bot keep its identity when a chat resets, a client changes, or work continues in the background.

The host treats the bot home as an owned boundary. Orca manages the files that describe the runtime connection, but preserves the owner's soul and memory. Creation and deletion therefore keep the record, home, workspace, automations, group membership, and tool access aligned.

References: src/…/bot-types.ts• L120-204 src/…/bot-home.ts• L121-233 src/…/bot-controller.ts• L94-127 src/…/bot-controller.ts• L141-187 src/…/bot-controller.ts• L286-312

Conversation and collaboration model

The bot's home chat is its ongoing conversation with its owner. Other chats can represent connector threads, automation runs, or background work. Each chat runs as a bot-scoped agent session, so its source and intended actor stay linked to the work it produces.

Groups add a shared room above those sessions. Each member bot has its own session. The room coordinates delivery, threads, peer requests, approvals, and stop actions. A reply mode can address all bots, one named bot, or only bots that the message mentions.

The following flow shows how a message becomes work for one or more bot sessions and returns as shared activity.

flowchart LR
    A[Owner or connector message] --> B{Conversation target}
    B --> C[Bot home chat]
    B --> D[Connector or automation chat]
    B --> E[Bot group room]
    E --> F[Member bot sessions]
    C --> G[Agent turn]
    D --> G
    F --> G
    G --> H[Reply, worker, item, or request]
    H --> I[Host activity and client views]

References: src/…/bot-chat-session.ts• L40-86 src/…/bot-chat-session.ts• L100-236 src/…/bot-chat-session.ts• L256-333 src/…/bot-group-runtime.ts• L48-85 src/…/bot-group-runtime.ts• L116-161 src/…/bot-group-delivery.ts• L21-99 src/…/bot-group-schema.ts• L7-103

Work items and owner attention

Bot work has two linked forms. Agent workers run in local, paired, or server-owned workspaces. Bot items give that work a durable owner-facing record with status, comments, links, questions, and history. The item view reads worker and pull-request facts from their source records, so an unavailable read does not become a false success.

Items turn bot activity into work that an owner can review. Open work can be planned, working, or waiting for the owner. Closed work can be done or canceled. Snooze and stale state guide attention without changing the work status. A Needs you item can carry a clear question with quick replies, so the owner can answer in the item and wake the owning chat.

References: src/…/bot-items.ts• L1-73 src/…/bot-items.ts• L183-208 src/…/bot-item-ask.ts• L45-58 src/…/bot-items-runtime.ts• L135-167 src/…/bot-items-runtime.ts• L220-270 src/…/BotItemView.tsx• L187-265

Connector access and tool capabilities

Connectors let a bot receive work from services such as Slack, Linear, GitHub, and Google. The bot record names its connected workspaces and the people allowed to ask it. When a connector user is not allowed, the platform creates an access request that the owner can review and grant or decline.

Agent tools use a separate capability boundary. Saved credentials stay on the host and are bound to the bot and credential. The agent receives an Orca relay grant instead of the saved secret. The relay adds the approved credential, can renew an Orca-managed sign-in, and stops calls when the bot, credential, or sign-in ends.

Access follows a chain of authority:

  1. A connector identifies a requester or an external event.
  2. The host checks the bot's connector and member policy.
  3. The owner grants access when approval is needed.
  4. Orca supplies only the connector or tool capability allowed for that bot.
  5. The bot turn records the source so activity and work remain traceable.

References: src/…/bot-types.ts• L68-103 src/…/bot-types.ts• L120-155 src/…/bot-access-request.ts• L28-113 src/…/bot-access-reach.ts• L104-123 src/…/bot-google-access.ts• L1-45 src/…/bot-tool-relay.ts• L46-88 src/…/bot-tool-relay.ts• L147-186

Background execution

Background execution lets a bot continue useful work without an open chat. Scheduled or owner-started runs can inspect connected context, update memory, create work items, and report results into Activity. Look around and memory tidy-up are host-managed examples that produce a suggestion or recorded result.

The host controls when a run may start and how much awake time it may use. A scheduled run needs a full wake and is deferred when power is not safe. If the run exceeds its awake-time limit, the host stops the turn and records that it did not complete normally.

References: src/…/bot-background-run.ts• L22-40 src/…/bot-background-run.ts• L50-65 src/…/bot-background-run.ts• L133-191 src/…/bot-background-run.ts• L194-279 src/…/bot-activity-host.ts• L154-209

Sharing and portability

Bot sharing packages selected parts of a bot for review before publication. A bot has one canonical share link. Publishing creates or updates the version served by that link. Stopping sharing revokes it. Receiving a bot reviews a specific version before creation and checks that the link still serves that version.

Sharing moves bot behavior without moving private credentials. Secret content is blocked from publication. The review keeps the source version and package digest, so an old review cannot silently create a newer bot.

References: src/…/bot-share-service.ts• L45-129 src/…/bot-share-service.ts• L131-147 src/…/bot-share-service.ts• L221-287 src/…/bot-share-service.ts• L313-347

Execution and client boundaries

Host execution

The execution host is the machine that owns a bot's home, workspace, agent sessions, and local records. Work can also run on a paired computer or server. Work records keep the execution host and workspace lineage so Activity can show where the agent actually ran. A workspace handed to a bot remains the bot's work even when another coordinator owns the worker inside it.

The desktop runtime is the source of truth for bot records and host activity. Its Activity view joins chats, connector links, automation runs, live agent status, recorded workers, handed workspaces, and suggestions into one client-neutral read.

References: src/…/bot-types.ts• L120-129 src/…/bot-work-runtime.ts• L75-145 src/…/bot-work-runtime.ts• L220-259 src/…/bot-activity-host.ts• L30-56 src/…/bot-activity-host.ts• L139-209

Desktop and mobile presentation

Clients read host-scoped bot listings and use the same bot identifiers, workspace scope, activity facts, and access decisions. The desktop presentation groups owner attention around Items, Chats, and Activity. It also exposes automations, settings, suggestions, connector setup, and access requests.

Mobile can list bots from the paired desktop and reachable relay servers, keep the last usable listing during reconnect, and open a bot on the host that owns it. Bot links resolve a bot home, session, or access request by host identity instead of name alone. Group rooms use the authoritative host transcript and support messages, reply audience, stop actions, approvals, and membership changes.

See bot conversations and automation for detailed conversation and automation behavior.

References: src/…/BotActivityPanel.tsx• L53-65 src/…/BotActivityPanel.tsx• L97-243 src/…/BotNeedsYouSection.tsx• L315-421 src/…/BotUpNextSection.tsx• L263-337 mobile/…/use-host-bots.ts• L51-109 mobile/…/BotLinkRouter.tsx• L34-79 mobile/…/BotSessionLinkResolver.tsx• L77-164

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the bot record, home files, home workspace, chat session, automations, groups, and tool grants consistent across create, update, agent change, and delete flows.
  • Keep bot and group operations serialized with session admission so a reset, stop, membership change, or retry cannot act on a retired session.
  • Keep item ownership, chat roots, worker lineage, live workspace facts, pull-request facts, and owed activity mail aligned when item or orchestration contracts change.
  • Keep connector member policy, access-request expiry and redemption, Google reach, link owner data, and client refresh signals aligned.
  • Keep tool credential sealing, bot-folder binding, relay grants, sign-in revisions, session identity, revocation, and deletion cleanup aligned.
  • Keep background-run wake checks, awake-time limits, stop behavior, sleep markers, suggestions, and Activity results aligned.
  • Keep share package selection, review version checks, digest checks, secret filtering, canonical-link behavior, and recipient creation aligned.
  • Keep execution-host identity and workspace lineage in desktop reads, mobile listings, bot links, group routes, and notification targets.

Important failure modes

TriggerConsequenceGuard
A bot record and its home folder disagreeThe host can open the wrong identity or restore a deleted botBind the home to bot.json, validate ownership, and persist record changes with the home operation
A bot chat is reset while a message is being admittedThe message can enter an old session or create two home chatsHold a per-bot lock through session selection and message admission
A group delivery or worker admission is interruptedSome members can miss a turn or receive a duplicate turnKeep per-room queues, operation ids, pending delivery records, and startup resume
A worker or workspace read is unavailableActivity can claim work is done or hide work that still runsPreserve lineage and show unknown or missing state instead of inferring success
An access request expires or is redeemed on another hostThe requester is added to the wrong bot or remains falsely pendingUse single-use tokens, host ownership checks, and explicit redemption outcomes
A tool credential changes during an agent callA request can use an old sign-in or an ended secretBind credentials to the bot and credential id, revoke open calls, and fence sessions
A scheduled run starts during a dark wake or exceeds its awake limitThe run can stall, consume an invalid slot, or continue without a trustworthy resultRequire full wake, track awake time, and stop late turns
A share review refers to an older link versionA recipient can create content that the owner did not approveRe-resolve the link and compare its version before creation
A mobile link matches several hosts or a host is outdatedThe phone can open an unrelated bot or fail without contextResolve host answers, offer a picker, and report update or reachability state

Key files

FileWhy to read it
src/…/bot-types.tsThe durable bot identity, connector links, member policy, chat link, work preferences, and provenance fields
src/…/bot-controller.tsThe bot lifecycle and the relationship between records, homes, workspaces, groups, and automations
src/…/bot-home.tsThe bot home boundary, owner files, generated files, memory seed, and ownership check
src/…/bot-chat-session.tsHome-chat creation, reset, message delivery, native-session admission, and background session choice
src/…/bot-group-runtime.tsGroup room lifecycle, delivery ownership, peer scope, and recovery
src/…/bot-group-delivery.tsGroup message admission, audience selection, reply collection, and replay
src/…/bot-work-runtime.tsWorker lineage, execution hosts, workspaces, connector conversation links, and work context
src/…/bot-activity-host.tsThe client-neutral Activity view assembled from chats, workers, automations, and handed workspaces
src/…/bot-items.tsThe owner-facing work-item contract and the meaning of statuses, links, stale state, and attention
src/…/bot-items-runtime.tsItem persistence, worker and pull-request joins, chat ownership, and recovery mail
src/…/bot-access-request.tsConnector access requests and the member changes that a grant permits
src/…/bot-access-reach.tsThe shared view of what a person can reach through a bot
src/…/bot-tool-credentials.tsHost-side storage and authority rules for bot tool credentials and OAuth records
src/…/bot-tool-relay.tsThe boundary that turns a bot's local grant into an authenticated upstream tool call
src/…/bot-share-service.tsShare preview, review, publication, update, receipt, and revocation semantics
src/…/BotActivityPanel.tsxThe desktop owner view for items, activity, automations, and suggestions
mobile/…/use-host-bots.tsHost and server bot listings, refresh behavior, execution-host scope, and last-known data
mobile/…/BotLinkRouter.tsxBot-link host resolution, access-request redemption, host choice, and link failure states
mobile/…/BotSessionLinkResolver.tsxMobile opening of bot home and session links through the owning host