Orca (plugin)
The Orca plugin (extensions/orca) connects the gateway to Orca
hosts. Operators pair hosts and grant access in Control UI v2; granted users see their Orca agent
sessions in a panel in the web client, read terminal screens, answer agent requests, and launch
new sessions.
The gateway reaches an Orca host through one of two transports:
- paired: the gateway pairs with the Orca runtime and speaks Orca’s end-to-end encrypted protocol. Full feature set, including structured chat sessions.
- cli: the gateway runs the
orcaCLI, on the gateway host or on a WednesdayAI node. Terminals, worktrees and repos only; no chat sessions.
Admin guide
Enable the plugin
Orca is a bundled plugin and is disabled by default:plugins.entries.orca.enabled: true, then restart the gateway.
The Orca page in Control UI v2 is a plugin module, and plugin modules load only when allowlisted
(see Control UI plugins):
Pair a host
- In the Orca desktop app, create a pairing code.
- In Control UI v2, open Orca → Hosts, enter a Label (up to 48 characters) and paste the
Pairing code under Pair Orca host. Either the
orca://pair?code=…link or the Orca web link (…/web-index.html#pairing=…) works. A code pairs once: WednesdayAI exchanges it for its own device token, so pairing again needs a new code. - The host appears in the hosts table with its endpoint, scope, and state. Unpair it from the same table.
<stateDir>/orca/pairings.json (written atomically, mode
0600). Paired target ids start with p-.
The code’s scope decides what the gateway can do:
- Mobile codes get the phone app’s method set. Users can launch an agent into an existing
worktree. Launching into a new worktree also needs
worktree.createin Orca’s mobile method set, which current Orca releases include. - Runtime codes (Orca’s Shared Server Access) get the full runtime method set.
orca-method-unavailable and one of these messages:
- “This Orca host cannot launch agents for WednesdayAI; update Orca on that host.”
- “This Orca host cannot serve chat sessions to WednesdayAI; update Orca or turn chats on.”
CLI fallback targets
When native pairing is not available, configurecliTargets. Each target runs the orca CLI:
A node target needs the CLI on the node’s exec allowlist. Use the absolute path:
orca-node-offline, orca-node-command-denied, or
orca-node-exec-denied; a missing binary as orca-cli-missing.
The node’s exec approvals record the last command that matched an allowlist entry
(lastUsedCommand). The record goes on the agent’s own entry for that pattern when one
exists, otherwise on the "*" entry added with --agent "*". For terminal sends and
launches, the WednesdayAI node host records the text and prompt as
--text=[redacted] and --prompt=[redacted]. Native app nodes, and node
hosts that run commands through the macOS app exec host, do not apply this redaction yet
(WednesdayAI-apps#63). On those
nodes the record includes the sent text or prompt; if it is sensitive, use a paired target
instead.
Other settings
Grants
Access is off for every user by default. Grant it per person inplugins.entries.orca.config.access.users, or from the Access tab of the Orca page in
Control UI v2:
targets: target ids, or"*"for every target.mode:read(see sessions and screens) orcontrol(also send input, answer requests, message, and launch).- The key is the person id from
session.identityLinks; the user’s device must be linked. - Grant edits go through
config.patchand take effect after the gateway restarts.
User guide
When you hold a grant, the web client sidebar shows Orca below Inbox, with a badge counting sessions that need attention. The panel:- lists agent sessions on your granted hosts, with state, plan, and attention messages;
- opens a session to show its terminal screen, or its chat and pending requests on paired hosts;
- with
control: types text or keys (enter, escape, arrows, tab, ctrl-c) into the terminal, answers approvals and questions, and sends chat messages; - with
control: launches a new session for an allowed agent, in an existing worktree or a new one.
read grant shows everything without input controls. If
Orca starts a session but does not deliver or confirm your prompt, the panel says so and shows the
prompt so you can copy it and send it from the session; it does not launch again.
Developer notes
- Gateway API: the versioned
orca.v1.*methods, documented in the Orca API reference. - Control UI v2 module:
extensions/orca/ui/index.js(vanilla JS). The web client panel is native code inapps/web/src/ui/orca/; no plugin JS runs in the web client. - Transports implement
OrcaBackend(extensions/orca/src/backend.ts).
Vendor-sync policy
Orca’s runtime RPC is internal to Orca and has no stability promise. The plugin tracks it:- Orca’s client crypto and pairing modules are vendored verbatim into
extensions/orca/src/vendor/orca/. Do not edit them by hand. - The RPC contracts the plugin calls are hand-mirrored.
extensions/orca/scripts/orca-upstream.jsonpins the upstream commit and records the hash of each vendored and mirrored upstream file. - Every backend response is parsed leniently, so drift fails loudly with
orca-bad-outputororca-method-unavailable.
--check fails and names the changed upstream files when Orca drifted from the recorded commit.
When a mirrored file changes, update its usedBy files, then --write.
Upstream drift report
extensions/orca/scripts/orca-drift-report.ts runs the --check comparison against the latest
stablyai/orca main and keeps one GitHub issue current. It runs locally on a timer, because
GitHub Actions is limited to release and publish jobs. It needs git and a gh CLI that can
create and edit issues on ExpansionX/WednesdayAI-core.
--orcadefaults to${XDG_CACHE_HOME:-~/.cache}/wednesdayai/orca-upstream, which is cloned on the first run. Each run fetchesmainand detaches HEAD on it. A checkout with uncommitted changes is refused. Use a dedicated checkout, not one you work in.- No drift: exits 0 and makes no GitHub call.
- Drift: opens an issue titled “Orca upstream drift: vendored or mirrored files changed on
stablyai/orca main” (labels
factory-backlog,severity:low). The issue lists the changed files, the plugin files that mirror them, and agit diffcommand for each. Later runs edit the open issue when the drift changes, and leave it alone when nothing changed. Running it twice is safe. - Exits 1 when
gitorghfails.
WorkingDirectory to your
checkout:
node comes from a version manager, put its absolute path in ExecStart. If gh cannot
reach its keyring from a user service, set GH_TOKEN through EnvironmentFile=.
Or use cron: