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.11: Production Hardening — IN PROGRESS | v1.0: UAT-gated (cut separately after v0.11 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 — mTLS by default; 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.10.19)
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash -s -- --version v0.10.19

# 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.8.15 to v0.10.19"

Subcommands

Command	Description
orca init	Initialize local orca state with full bootstrap
orca status	Show orca daemon status
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
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
orca drift	Drift detection: show, watch, acknowledge, remediate, config
orca txn	Transaction management: apply, list, show, rollback
orca collector	Collector/aggregator management: start, stop, status
orca cluster	Cluster management: cutover, rotate-lead, compat-check

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
mTLS	—	mTLS by default; no opt-in required
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

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

Architecture

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

License

MIT — see LICENSE.