orca-agent treats argv as leakable and full-auto as a late switch

The stdin route exists because argv is visible to other processes

The headless invocation offers two forms and prefers one for a specific reason:

orca exec "fix the failing test"          # run headlessly
printf '%s' "$INSTRUCTION" | orca exec   # keep arbitrary prompt text out of argv

The comment is the design note: keep arbitrary prompt text out of argv. The stated threat is precise rather than general. When the prompt may contain tokens that a task later searches for, or that it kills in the process table, passing the prompt as a positional argument exposes it to anything on the machine that can read the process list. The positional form is still supported for convenience, and on Windows the same idea is handled by assigning the key to a shell variable first and then using the same orca commands. A task that greps its own history or terminates a matching process will not find your instruction on the command line, which is the whole point of the pipe.

Folder trust governs what Orca reads, not what it can reach

The first run in a directory asks you to trust it or continue untrusted, and the distinction is easy to misread. Trusting a folder lets Orca load that project configuration, instructions, skills, agents, and workflows. What trust explicitly does not do is enable or bypass the OS sandbox. Those are two separate layers and the prompt only gates the first. The consequence is a specific trap: someone may read the trust question as the sandbox decision, approve it, and conclude the session is isolated. It is not. Isolation is configured elsewhere, through the shell sandbox and permission profile that the status command reports. Untrusted mode is therefore not a sandbox either, it is a mode in which the project files that would shape your agent are simply not loaded.

full-auto asks twice, applies late, and does not reach back

Approval modes are cycled with Shift+Tab through suggest, auto-edit, full-auto and plan. A tool call that needs approval turns the input into a panel offering allow once, allow this exact call, allow the tool for the session, or deny with Esc. Entering full-auto then asks for a separate explicit Full Access confirmation. Three timing details make this safer than it first appears. The running task picks the new mode up at its next tool call, so nothing already in flight changes underneath you. Tools already running and subagents already launched keep their original policy, meaning an in-progress edit is not retroactively upgraded to full access. And mode changes last for the session and are never saved, so you cannot end a session in full-auto and discover it persisted into the next one. Model and reasoning-effort choices are the opposite: those are written to your user config.toml and do carry over.

Four ways to name the session you want back

Session addressing is more varied than most agents bother with. The headless path takes an explicit identifier, the most recent session, or an identifier plus a message boundary:

orca exec resume SESSION_ID "continue"    # resume a headless session
orca exec resume --last "continue"        # resume the most recent session
orca exec resume SID --resume-at MID "continue"  # resume up to a message boundary

The interactive path adds a bare form that accepts an identifier optionally, and on exit Orca prints the resume command it would take, so the identifier never has to be copied out of a log by hand. Inside the UI, slash commands cover the rest: /new, /resume grouped by project with fork, rename, archive, delete and copy ID, /fork with a name, /rename with a name, and /copy taking a count. The message-boundary form is the one worth understanding. Resuming at a mid-point rather than at the end of the transcript is what lets you branch a conversation back to an earlier decision instead of restarting the task from nothing. Orca also has opt-in shared sessions on Unix, driven by orca daemon, orca attach and orca acp-bridge, plus file-defined subagents and persistent terminal output pages. That bridge is what makes the agent reachable from another program: Pilion Browser acts as an ACP client, launches orca in ACP mode, forwards the API key, and exposes its own tabs as MCP tools named browser_snapshot, browser_screenshot, navigate, click and type, with approval before each action and a human takeover path.

One command entry point, and Windows gets two dialects

Every command the agent runs goes through a single entry point named bash, which removes a whole class of per-shell quoting logic from the core loop. Windows is where the exceptions accumulate, and they are documented rather than implied. Protocol command arrays are launched as native Windows argv with no shell re-parsing at all, while legacy string commands still go through the resolved shell dialect, so the two forms are not interchangeable. On Windows, Orca prefers PowerShell 7 and detects its standard installation path even when it is not on PATH. Restricted sessions fall back to cmd.exe when PowerShell 7 is unavailable, and Windows PowerShell 5.1 is an explicit option only for modes that do not require AppContainer isolation. In other words, the isolation-capable modes require PowerShell 7, and the fallback is a different isolation story, not a worse one.

Four install routes, and one of them provisions the sandbox

The npm route is the shortest, under a scope that does not match the repository name:

npm install -g @blade-ai/orca

The native route pipes a script, with a PowerShell equivalent on Windows:

curl -fsSL https://orcaagent.dev/install.sh | sh

irm https://orcaagent.dev/install.ps1 | iex

The same PowerShell script takes a switch that runs from a project directory to provision that folder restricted sandbox capability, which is a separate step from installing the binary at all. The npm package covers macOS, Linux and Windows on ARM64 and x64, and prebuilt archives are on the GitHub releases page. The tree also holds install.sh and install.ps1 as first-class files rather than generated artifacts. One oddity worth noting for anyone auditing the build: a Rust workspace also contains a Python package. The pyproject.toml declares a distribution named terminal-bench-orca at version 0.1.0 requiring Python 3.11 or newer, with an empty dependency list and packages limited to terminal_bench.

serde_json float roundtrip and a matcher pinned to a commit

The workspace manifest explains its own unusual dependency choices, and two entries stand out. serde_json is pulled in with a float_roundtrip feature rather than the default, and the comment above it gives the reason: digests over re-serialized payloads, naming child relay envelopes and surface batches, need every f64 to parse back to the exact value it was written from. Without that feature a digest computed on a value and a value parsed from a digest can disagree, which would surface as integrity failures that look like corruption rather than like a float rounding issue. The second is nucleo, a fuzzy matcher, which is not taken from a registry release at all but from a git URL with the revision spelled out as 8c16d47cdfa9607d3e44df5f81c635c6f43c65ee. Pinning to a commit rather than a version means reproducible builds, at the cost of a dependency whose update has to be made deliberately. The same discipline appears elsewhere in the manifest. The agent client protocol crate is pinned with an equals sign to 0.10.4 and built with its unstable feature enabled, which is a library API expected to change. ratatui-image is pinned the same way at 9.0.0, and the workspace declares resolver 3, meaning it targets a modern Cargo feature set rather than inheriting a legacy resolution mode.

Ctrl+Enter only works where the terminal supports it

Most of the interface works the same everywhere, and one binding does not. Mention and command syntax is plain: @ mentions files, skills, plugins and MCP resources, a dollar sign inserts a skill, a slash opens the command menu, a question mark lists every key, and Ctrl+V attaches an image from the clipboard. Output is deliberately compressed: replies are marked with a filled circle, reasoning collapses into a single thinking line, and each tool call shows its output under a vertical rail. Ctrl+O expands the most recent collapsed output and Ctrl+Shift+O expands all of them, so the default view stays readable during a long turn. The exception is steering a running turn. Esc interrupts it, Enter queues a follow-up for the next turn, Ctrl+Enter sends it into the turn already in flight, and Ctrl+B moves that turn to the background. That Ctrl+Enter binding is documented as available only in terminals implementing the kitty keyboard protocol, so in a terminal without it the same key does something else entirely and your injected instruction silently becomes a queued one. The status bar is the place to confirm what actually took effect: it reports the approval mode, the model and reasoning effort, the context left, and usage.

Editorial conclusion

Use Orca if your agent work happens in a terminal you script, because the headless path has a verifier flag, four different ways to resume a session and a stdin route that keeps sensitive prompt text out of the process table. Before running full-auto anywhere real, read the approval section twice: the confirmation is separate, the change lands only at the next tool call, and already-running tools keep their old policy. Verify the sandbox story on your own platform rather than trusting the trust prompt, since folder trust governs what configuration Orca loads and grants nothing about OS isolation.

Frequently asked questions

Official sources

1. echoVic/orca-agent on GitHub
2. Issues
3. License: MIT
4. README
5. Releases