Orca

A minimalist, offline-first, CLI-first orchestration engine inspired by HashiCorp Nomad. Proxmox is one supported node type — not the project's identity.

Status

v0.12: Security Hardening (Zero-Trust Identity) — COMPLETE | v0.13: Production Hardening Round 2 + UAT Plan — IN PROGRESS | v1.0: UAT-gated (cut separately after v0.13 completion per operator decision)

See .ciagent/ROADMAP.md for the full roadmap.

Pillars

• Simplicity — single binary, minimal dependencies, no daemon on the critical path
• Offline-first — no cloud dependencies; the cluster is the OS
• CLI-first — the command line is the primary interface (humans and AI agents)
• Security before features — SSH-push is the canonical transport (mTLS available for daemon mode); NFRs ship before new functionality
• WASM-first — workloads target OS primitives (systemd units, journald), not a container runtime shim
• Bug fixes before features — stability is paramount

Quickstart

Install (1-liner)

# User-level install (binary at ~/.local/bin/orca, state at ~/.orca)
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash

# System-level install (binary at /usr/local/bin/orca, state at /root/.orca)
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | sudo bash -s -- --system

# Pin a specific version (latest tag: v0.12.10)
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash -s -- --version v0.12.10

# Dry-run: check what would be installed without writing
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash -s -- --check

Then initialize local state and verify:

orca init          # creates ~/.orca/ (or /root/.orca with --system)
orca version       # prints version info
orca --help        # show all subcommands

Build from source

make build         # Build binary to ./bin/orca
./bin/orca init    # Initialize local state
./bin/orca version # Verify

Update in place

Re-running the installer updates the binary while preserving your config, database, and certificates in the namespace dir:

curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash
# → "updated orca from v0.11.28 to v0.12.10"

Subcommands

Command	Description
orca init	Initialize local orca state with full bootstrap
orca status	(deprecated v0.1 stub) Show orca daemon status — use orca node list + orca metrics /healthz
orca version	Print version information
orca daemon	(deprecated) Run the orca daemon (HTTP API + health checks)
orca metrics	Start metrics endpoint (Prometheus text exposition)
orca logs	Aggregate journald logs across nodes (--all-nodes --since)
orca backup	Create a signed tar.gz backup of ORCA_HOME
orca restore	Restore ORCA_HOME from a verified signed backup
orca upgrade	Upgrade orca to a new version (thin wrapper; R-017 cutover)
orca node	Manage orca nodes: join, leave, list, key-reset, drain, capacity
orca job	Manage orca jobs: run, list, stop, logs, lint, verify, migrate, restart
orca ns	Manage orca namespaces: list, create, delete, inspect, validate, inherit, set-constraint
orca cert	(deprecated) Manage orca certificates: ca-init, gen, show, renew, fingerprint
orca doctor	Run self-checks: cert, network, db, os, proxmox, no-orca-on-server, nft, audit, modes, oidc, db-retention
orca audit	View orca audit log (list)
orca cache	CLI cache management: show, invalidate, invalidate-all
orca acl	ACL management: grant, revoke, list, check
orca secrets	Secrets management: set, get, list, rotate, delete, rotate-master
orca drift	Drift detection: show, watch, acknowledge, remediate, config
orca txn	Transaction management: apply, list, show, rollback
orca nft	nftables ingress management: show, diff, doctor, country block, rate limit
orca collector	Collector/aggregator management: start, stop, status
orca cluster	Cluster management: cutover, rotate-lead, compat-check, seal, unseal
orca auth	OIDC authentication: login, logout, status, init-idp, register
orca peer-setup	Create the orca system user + drift-events dir on a peer (REQ-111)

See docs/cli.md for the full CLI reference with all flags and examples.

Honest trade-offs

Orca is not a Kubernetes replacement for every workload. This table is the honest comparison — K8s wins in several dimensions, and that is acknowledged rather than papered over.

Dimension	Kubernetes wins	Orca wins
Ecosystem	Mature CNCF ecosystem; vast operator, controller, plugin surface	—
Talent pool	Large pool of K8s-experienced engineers	—
Multi-cloud	Portable across all major clouds; control plane is cloud-agnostic	—
Stateful operators	Rich operator pattern (CRD + controller) for stateful workloads	—
Service mesh	First-class service mesh (Istio, Linkerd)	—
Auto-scaling	Cluster autoscaler, HPA/VPA, deep integrations	—
Daemon footprint	—	No daemon on the critical path; the cluster is the OS
OS-native	—	Workloads are systemd units + journald; no container runtime shim
Transport	—	SSH-push is canonical (no daemon needed); mTLS available for daemon mode
Offline-first	—	No cloud dependencies; fully air-gapped operation
WASM-first	—	Workloads target OS primitives, not a container runtime
Proxmox	—	First-class Proxmox node type (--type proxmox) via SSH-push

Documentation

Document	Description
docs/cli.md	CLI reference — every command, flag, and example
docs/jobspec.md	Jobspec reference — markdown frontmatter schema
docs/ingress.md	Ingress guide — Traefik configuration
docs/namespace.md	Namespace and path layout
docs/install.md	Installation guide
docs/security-scanning.md	Security scanning tools
docs/security-runbook.md	Security runbook — seal/unseal, rotation, incident response
docs/webauthn.md	WebAuthn / passkeys registration and login
docs/threat-model.md	STRIDE threat model + zero-trust architecture
docs/oidc.md	OIDC configuration — Dex quickstart, BYO IdP

Examples

Example	Description
examples/full-stack/	Full-stack deployment with ingress (5 services + rendered artifacts)

Development

make build         # Build binary to ./bin/orca
make test          # Run tests
go vet ./...       # Vet all packages
make lint          # Run gofmt + go vet + shellcheck
make verify-reqs   # Assert ROADMAP ↔ REQUIREMENTS consistency
make verify-docs   # Assert docs/cli.md ↔ `orca --help` consistency

Architecture

See .ciagent/ARCHITECTURE.md for full architecture details.

License

MIT — see LICENSE.