ORCA DOCS

Local runtime guardrails for AI agents.

Build Orca from source, initialize policy, run agents through the supervised CLI, and add host plugins for Codex, Claude Code, OpenCode, and OpenClaw. The CLI is the source of truth for policy decisions.

VERIFIED AGAINST

Source: christopherkarani/Orca
Release: v1.1.0
Zig: 0.15.2
Policy path: .aegis/policy.yaml

INSTALL

Build from source

Orca is a Zig CLI. The current repository pins Zig 0.15.2. Build from the public repository, install into a local prefix, then put the binary on your PATH.

Source install

git clone https://github.com/christopherkarani/Orca.git
cd Orca

zig version
zig build -Doptimize=ReleaseSafe
zig build -Doptimize=ReleaseSafe --prefix ~/.local

export PATH="$HOME/.local/bin:$PATH"
orca --help
orca doctor

Use release docs for packaging

Verify artifact checksums and platform notes in install.md before moving a binary to another machine.

QUICKSTART

Start protected work

Run doctor first. It reports which protections are active, limited, wrapper-only, observe-only, or unavailable on your platform.

Setup

orca doctor
orca init --preset generic-agent
orca policy check .aegis/policy.yaml

The strongest local protection is launching the agent as an Orca-managed child process. Plugins add host hooks, but they do not replace the runtime wrapper.

Run

orca run -- codex
orca run -- claude
orca run -- opencode
orca run -- openclaw

CLI overview

orca --help
orca version
orca doctor
orca init --preset generic-agent
orca policy check .aegis/policy.yaml
orca run -- <agent-command>
orca replay --session last --verify
orca redteam --ci

POLICY

Deny by default

Policies are YAML with version: 1. Explicit denies beat allows. CI mode never prompts; ask decisions become deny unless an explicit allow rule applies.

Policy example

version: 1
mode: strict
workspace:
  root: "."
  write_mode: staged
env:
  inherit: false
  allow:
    - PATH
    - HOME
commands:
  default: deny
  allow:
    - "git status"
    - "zig build *"
  deny:
    - "rm -rf *"
    - "curl * | sh"
network:
  mode: allowlist
  default: deny
audit:
  level: full
  redact_secrets: true
  tamper_evident: true

Explain a denial

Use policy explain commands when a file, command, network request, or MCP tool is denied.

Explain

orca policy explain command git status
orca policy explain file.read ./.env
orca policy explain network https://example.invalid/path

INTEGRATIONS

Add host plugins

Plugins call the Orca CLI for decisions, diagnostics, red-team checks, and replay. Keep orca on your PATH; plugins do not bundle the CLI.

Codex

Repo marketplace source. Install from Codex after adding the source.

Integration docs

Install

codex plugin marketplace add christopherkarani/Orca

Strongest protection

orca run -- codex

Claude Code

Repo marketplace source with hooks and slash-command helpers.

Integration docs

Install

claude plugin marketplace add christopherkarani/Orca
claude plugin install orca@orca --scope user

Strongest protection

orca run -- claude

OpenCode

npm plugin. Keep the Orca CLI separately available on PATH.

Integration docs

Install

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["orca-opencode-plugin"]
}

npm install orca-opencode-plugin

Strongest protection

orca run -- opencode

OpenClaw

Local path, npm, and ClawHub install paths are documented.

Integration docs

Install

openclaw plugins install ./integrations/openclaw-plugin
openclaw plugins install npm:orca-openclaw-plugin
openclaw plugins install clawhub:orca-openclaw-plugin

Strongest protection

orca run -- openclaw

Plugin diagnostics

orca plugin doctor codex
orca plugin doctor claude
orca plugin doctor opencode
orca plugin doctor openclaw

orca plugin manifest codex
orca plugin manifest claude
orca plugin manifest opencode
orca plugin manifest openclaw

orca plugin install codex --dry-run
orca plugin install claude --dry-run
orca plugin install opencode --dry-run
orca plugin install openclaw --dry-run

LICENSE

Activate a paid license

Pro and Team purchases create an account on this website and issue a signed Orca license key. The local CLI verifies the signature with the matching public key embedded in the Orca repo. Orca does not need to call this website while your agents run.

If your browser session is gone later, sign back in with Clerk using GitHub or email to view the same account and license.

Buy Pro or Team

Copy the license from Account

Run the activation command

Use Orca locally

Activate

orca license activate <key>
orca license status

SECURITY

Know the boundary

Local first

Local policy decisions, redaction before persistence, auditability, replay, and no telemetry by default.

Wrapper strongest

Host hooks are additive. Use orca run for supervised execution.

No magic sandbox

No universal transparent filesystem or network enforcement, kernel isolation, or protection outside Orca.

Replay

orca replay --session last
orca replay --session last --json
orca replay --session last --only denied
orca replay --session last --verify

Red-team

orca redteam --ci
orca redteam --json --ci > redteam.json

TROUBLESHOOTING

Debug a setup

Start with the binary, policy, and latest replay. If a capability is reported as limited, wrapper-only, observe-only, or unavailable, treat it as weaker protection until the platform backend says otherwise.

Troubleshoot

zig version
zig build -Doptimize=ReleaseSafe

orca doctor
orca policy check .aegis/policy.yaml
orca replay --session last --only denied
orca redteam fixtures --fixture prompt-injection/readme-env-read --ci

UPSTREAM DOCS

Quickstart Policy Red-team Replay Troubleshooting Plugin security model