Orca Agent: A DeepSeek-Native Coding Agent for the Terminal

What Orca Actually Is and Who It Is For

Orca is a coding agent that runs in your terminal. The README describes it plainly: give it a task and it reads code, edits files, runs commands, verifies the result, and keeps working until the task is done or it needs you. It is written in Rust, runs locally, and ships under the MIT license. There is no hosted control plane in the description; the binary is the product.

The intended user is someone who already has a DeepSeek API key and wants an agent that talks to that API natively rather than through a generic adapter layer. The README says Orca uses DeepSeek's reasoning and tool-use semantics directly, with SSE streaming, prefix-cache-friendly prompts, automatic context management, and retry logic. That is a deliberate narrowing. If your team standardizes on a different provider, this project is not trying to be your harness.

The second audience is automation. The TUI is for interactive work, but orca exec exists for scripts and CI, and the README shows a headless invocation with a verifier command attached. That split matters because the two modes have different failure behaviour: an interactive session can ask you a clarification question, while a headless run cannot.

A third, smaller audience is editor integrations. orca --mode=acp connects an ACP client, and the Cargo workspace pins agent-client-protocol at =0.10.4 with the unstable feature enabled. Pinning an exact version plus an unstable feature set is a signal that this integration surface moves, so treat it as a moving target rather than a stable contract.

How the Agent Loop, Sandbox and Task Model Fit Together

The mechanism visible in the README is a loop with a permission gate in the middle. Orca reads, searches, edits and writes code, runs shell commands, and can verify the result with a command you choose. Risky actions are gated by four modes: suggest, sandboxed auto-edit, full-access full-auto, and read-only plan, plus per-folder trust. The distinction between mode changes and model choices is explicit: model and reasoning-effort choices from /model or /config are saved to the user config.toml and apply to new sessions, while approval mode changes stay session-scoped and are never saved.

The most interesting design decision is how shell commands are treated. bash is the only command entry point, and every command it starts belongs to the task rather than to the tool call. A long build, a CI watch, or an interactive PTY session keeps running after the call returns. The README draws a sharp line between yield_time_ms, which bounds only how long the call waits, and timeout_ms, which is the sole caller-side execution deadline. Continuation happens through task_read_output, task_send_input, task_wait and task_stop, keyed by a task_id. A background supervisor settles exited or stopped sessions without polling and injects one bounded completion notification before the next model turn. This is a different mental model from agents where a shell call is a synchronous request-response, and it is the part of the design most likely to surprise a new user.

Subagents get a similar treatment. Synchronous subagents, async subagents, and workflow child agents each receive a runtime-owned continuation id, and a later subagent call can pass resume_from with that id or the originating task id to append a new prompt to the same durable child conversation. All of these run through one durable execution scope per root task tree. The README notes that the default 32 execution leases are a capacity ceiling rather than a delegation target: accepted overflow queues without creating a worker, and parents waiting for children yield their lease before re-entering the fair queue. That is a queueing design, not a thread pool, and it explains why the README warns against reading 32 as a target.

Finally, /trust controls whether Orca loads project-provided configuration and instructions, and the README is explicit that it does not enable or bypass OS sandbox enforcement. Those are two separate concerns that are easy to conflate when reading the command list.

Installing Orca and Running a First Headless Task

The README gives two install paths. The npm package is the shorter one and supports macOS, Linux, and Windows on ARM64 and x64:

npm install -g @blade-ai/orca

Alternatively, install the native binary directly from the project's install script:

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

On Windows PowerShell the README uses a different one-liner:

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

Prebuilt archives are also published on GitHub Releases if you would rather not pipe a script into a shell.

Before running anything, export the API key. The README uses a placeholder value, and you should supply your own:

export DEEPSEEK_API_KEY=sk-...

On Windows PowerShell the equivalent is $env:DEEPSEEK_API_KEY = "sk-..."; the orca commands themselves are identical.

With the key set, opening the TUI is just orca with no arguments. For a first real task, the headless form is easier to reason about because nothing is waiting on your keystrokes:

orca exec "fix the failing test"

If you want the agent to prove the work before it stops, pass a verifier command. The README's example uses cargo test:

orca exec --verifier "cargo test" "fix it"

What you should see is the agent working the task and then either finishing or stopping to ask. On exit, Orca prints the exact orca --resume <SESSION_ID> command for the session, and headless exits print the resume command too, so you can pick the conversation back up with orca exec resume SESSION_ID "continue".

On Windows, restricted sessions rely on AppContainer isolation, and the README says to provision that capability from a project directory with:

& ([scriptblock]::Create((irm https://orcaagent.dev/install.ps1))) -SetupSandbox

Windows PowerShell 5.1 remains an explicit option only for modes that do not require AppContainer isolation, and restricted sessions fall back to cmd.exe when PowerShell 7 is unavailable.

Where Orca Gets in Your Way

The provider lock-in is the first real limitation, and it is by design rather than an oversight. Orca is DeepSeek-native. If your organisation routes model traffic through a gateway, or if you need to swap between Anthropic, OpenAI and a local model per task, this project does not offer that in the README. You would be adopting a second agent alongside whatever you already run.

Platform asymmetry is the second. The Windows path carries most of the caveats: AppContainer isolation needs the sandbox capability provisioned before restricted sessions work, PowerShell 7 is preferred and detected even when absent from PATH, and cmd.exe is the fallback. Windows PowerShell 5.1 is explicitly limited to modes that do not require AppContainer isolation. If your CI fleet is Windows and you cannot guarantee PowerShell 7, the restricted modes are not the ones you will be running.

The permission model has a sharp edge. Entering full-auto requires an explicit Full Access confirmation, and once the runtime commits it, the active task's next tool admission uses TrustedHost or DangerFullAccess. Tools already running and delegated children already launched retain their original policy snapshot. That is a sensible safety property, but it means a mid-task escalation does not retroactively cover work already in flight. If you assume otherwise, you will misjudge what a full-auto switch actually changed.

The documentation also has gaps. The README does not document rollback of file edits, and it does not describe an undo path for the agent's writes. The ACP daemon, file-defined subagents, and persistent terminal output pages are opt-in development-build features dated to v0.4.27 and later, and the README links to docs/acp-daemon.md, docs/subagents.md and an architecture ADR rather than describing them inline. If any of those three is the reason you are evaluating Orca, read the linked documents before installing, because the README alone will not tell you whether they fit your setup.

One more boundary worth stating: /trust governs project-provided configuration and instructions, not OS sandbox enforcement. Turning trust on does not turn the sandbox off, and turning it off does not sandbox anything by itself.

How Orca Differs from a Model-Agnostic Agent Harness

The obvious alternative is a provider-neutral coding agent, the kind that treats model selection as configuration and ships adapters for several APIs. The difference is architectural, not cosmetic. A neutral harness has to normalise tool-call formats, streaming events and reasoning traces across providers, which is why those projects tend to expose a compatibility layer and lag on provider-specific behaviour. Orca takes the opposite bet: it targets one provider's semantics and spends its complexity budget on the agent runtime instead. That is why the README can promise prefix-cache-friendly prompts and DeepSeek-specific retry logic, and also why swapping the backend is not a config change here.

The second alternative is a plain shell script plus a model API call. That gets you the single-turn case and nothing else. What Orca adds on top is the durable task model: commands that outlive the tool call, task_read_output and task_send_input to keep feeding them, a background supervisor that injects one bounded completion notification, and sessions you can resume or fork. If your work is one-shot prompts, the extra machinery is overhead. If your work involves a build that takes twenty minutes and a test suite that takes ten, the task model is the reason to use an agent at all.

A third alternative worth naming is the editor-integrated agent. Orca reaches editors through ACP rather than through a plugin, so the integration depends on your client supporting that protocol. The workspace pins agent-client-protocol at =0.10.4 with the unstable feature, which tells you the author expects churn on that surface. If your editor's ACP support is immature, the TUI and orca exec are the paths that will actually work today.

Maintenance, Licence and Upgrade Cost

The repository is not archived, and the last push was on 2026-09-17. Releases have been frequent and close together: v0.4.29 on 2026-09-12, v0.4.30 on 2026-09-13, and v0.4.31 on 2026-09-14. That cadence has a cost. Three patch releases in three days means the surface is still moving, and the README reflects that: /history is retired, /clear remains a hidden compatibility alias for /new, and several features are gated behind a v0.4.27 floor. If you pin a version, expect to re-read the changelog before jumping forward.

The upgrade path itself is cheap. The npm package is a global install and the native binary comes from a shell script or a release archive, so upgrading is re-running the installer. The expensive part is configuration drift, and the README is unusually clear about which settings survive a session: model and reasoning-effort choices are written to the user config.toml and apply to new sessions, while approval mode changes are session-scoped and never saved. That means a full-auto setting cannot silently persist into tomorrow's session, which is good for safety and mildly annoying if you wanted it to.

On licensing, Orca is MIT. That is permissive and imposes few obligations beyond keeping the copyright and permission notice with copies or substantial portions of the software. It is not legal advice, and your own policy on which licences your organisation accepts is the thing to check, not a summary here. One practical note from the repository layout: the Cargo workspace pulls nucleo from a git revision rather than crates.io, and pins agent-client-protocol and ratatui-image to exact versions. If you build from source rather than installing a prebuilt binary, those pins are what your build resolves against, and they are a supply-chain surface worth reviewing before you vendor the project.

Editorial conclusion

Adopt Orca if you already have a DEEPSEEK_API_KEY, want a local Rust binary with explicit suggest, auto-edit, full-auto and plan gates, and care about long-running commands surviving a tool call. Do not adopt it if you need a model-agnostic harness, since the README describes DeepSeek's reasoning and tool-use semantics as the foundation rather than one backend among several. Before committing, verify that your DeepSeek account and region work from your network, confirm the sandbox story on your platform (AppContainer on Windows, the restricted sandbox capability provisioned by install.ps1 -SetupSandbox), and check whether the opt-in daemon, subagent and terminal-page features you want are present in your pinned release, since the README dates those to v0.4.27 and later.

Frequently asked questions

Official sources

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