Orchestraitor

Orchestraitor - An agent harness with trust issues.

Orchestraitor is a local-first, security-first coding-agent harness and control plane that combines orchestration, provider/harness adapters, contextual token optimization, and a native developer experience — secured by Arbitraitor.

Its intended design combines a complete native agent loop plus adapters for existing harnesses (Claude Code, Codex CLI, Gemini CLI, OpenCode, Pi, and other ACP-compatible agents), enforced runtime isolation across native and wrapped agents, static plan-bound authorization before side effects, transactional filesystem tools, a trusted output boundary for files host tools may later execute, an explainable context compiler, and a low-overhead native control plane for TUI, IDE, and headless clients.

Relationship to Arbitraitor

Arbitraitor (arbsec/arbitraitor) is the exclusive security subsystem and authority for Orchestraitor. Every security-related primitive — policy evaluation, sandboxing, process and filesystem containment, network and secret brokering, command/package/plugin/artifact inspection, provenance, plan-bound approvals, output classification, promotion authorization, and tamper-evident receipts — is implemented in Arbitraitor. Orchestraitor owns orchestration, provider/harness adapters, context optimization, and developer experience, and never ships a parallel security authority. When a security capability is missing, it is added to Arbitraitor first (docs/spec/spec.md §2.2, §16).

Arbitraitor     Sole security engine and policy-enforced gate for untrusted artifacts/operations
Orchestraitor   Coding-agent harness and control plane that delegates all security to Arbitraitor

Status

MVP implementation in progress. The repository now contains early Rust crates for selected MVP subsystems, including the orcd daemon JSON-RPC server. There is no tagged release or installer yet. The API, CLI (orc / orchestraitor), daemon protocol, and configuration schema will change.

Early daemon surface

The orcd binary runs a JSON-RPC server over a Unix-domain socket using Tokio's current-thread runtime. It currently exposes:

• initialize — protocol version negotiation
• health — daemon status plus the Arbitraitor capability report from the startup probe (spec §6.7, §16.7); reports fail_closed when any required sandbox control is unavailable on the current platform
• shutdown — graceful shutdown within the five-second budget

By default, orcd listens at the first positional path argument, then ORCHESTRAITOR_DAEMON_SOCKET, then a temporary default path. SIGTERM triggers graceful shutdown within the five-second daemon budget from docs/spec/tech-stack.md §10.

This software is not production-ready. Security claims in the specification describe the intended design, not a shipped guarantee. Do not rely on Orchestraitor for isolation until a release exists and Arbitraitor reports effective controls for your platform (docs/spec/spec.md §6.7, §16.8).

Key design principles

• The agent is always untrusted — model, wrapped harness, repository content, tools, MCP servers, skills, and generated artifacts may behave incorrectly or maliciously (spec §6.1).
• A worktree is not a sandbox. The trusted controller owns Git metadata (spec §6.2).
• Approval belongs to the trusted UI, never to agent-generated text (spec §6.4).
• Static analysis narrows authority; it does not prove safety (spec §6.5).
• Arbitraitor is the sole security authority. Missing capabilities fail closed or run in an explicitly-labelled non-secure mode — never a silent duplicate (spec §6.7, §16.2).
• Transaction over mutation. Every change is a versioned transaction: capture stage, normalize, verify, review a compact diff, atomically promote or roll back (spec §9.5, §9.14).
• Opinionated by default, customizable by design, never mysterious about active config (spec §9.22.11).
• Incremental adoption. orc observe → orc wrap → orc connect → native; reversible, with orc disconnect restoring prior state in under 30 seconds (spec §9.18.2, MVP-2).

Specifications

• docs/spec/spec.md — product and architecture source of truth.
• docs/spec/tech-stack.md — concrete crates, versions, license compatibility, runtime dependencies, platform support, and rejected alternatives.

CLI

• orc init — deterministic local project detection that writes a proposed .orchestraitor/orchestraitor.toml; --dry-run writes nothing.

CLI configuration surface

The orc binary also exposes the configuration inspection and migration commands required by spec §9.22.3 and §9.22.8:

orc config get <key>
orc config explain <key>
orc config set <key> <value> [--layer=project|user|org|dir]
orc config unset <key> [--layer=project|user|org|dir]
orc config validate
orc config diff [--layer=project|user|org|dir] [--json]
orc config migrate
orc models refresh
orc models rollback

orc config explain reports the resolved value, source layer, source file, inherited state, and profile contribution placeholder. orc config validate rejects ambiguous same-layer conflicts (two shards under the same layer both defining the same key) and reports unknown keys. orc config migrate is forward-only, writes a .bak.* backup, and uses toml_edit so existing comments survive migration. orc models refresh forces an immediate models.dev catalog fetch into the local cache; orc models rollback returns to the previous cached snapshot without deleting manually configured models.

Contributing and security

• CONTRIBUTING.md — how to contribute to a spec-first, security-first Rust project, including when work belongs in Arbitraitor instead.
• SECURITY.md — report vulnerabilities privately; do not open public issues.
• AGENTS.md — always-active agent and contributor rule set.
• .agents/project/orchestraitor-workflow.md — MVP scheduling, review domains, documentation, and merge invariants.

License

Dual-licensed under MIT or Apache-2.0, matching Arbitraitor. All contributions are made under the Developer Certificate of Origin.