Jon Chery
61c97c847c
The fallback walk (REQ-098) reassigns VERSION from the requested
release to the nearest older release carrying a binary asset, but
never recomputed TARBALL (set once at line 106 from the requested
version). The stale tarball name then flowed into:
- grep -F "$TARBALL" SHA256SUMS -> matched nothing (the fallback
release's SHA256SUMS only lists the fallback tarball)
- sha256sum -c - -> empty stdin -> "no properly
formatted checksum lines found" -> REQ-132 refusal
- tar -xzf "${TMPDIR}/${TARBALL}" -> would look for the wrong
filename (download saved under the stale name too)
User-visible symptom (v0.14.2 latest had no asset, fell back to
v0.12.18):
install: verifying checksum...
sha256sum: 'standard input': no properly formatted checksum lines found
install: error: checksum verification failed (REQ-132); refusing to install
Fix: recompute TARBALL immediately after VERSION is reassigned in the
fallback branch, so download/grep/sha256sum/tar all reference the
fallback version's tarball. ASSET_URL and SHA256SUMS_URL were already
correct (derived from the API/ASSET_URL); TARBALL was the only stale
variable.
Reproduced the exact error before the fix; confirmed end-to-end
install succeeds after (orca-v0.12.18-linux-amd64.tar.gz: OK ->
extracting -> installed). Added a bats regression test pinning
--version v0.14.2 and asserting the dry-run "would install" line
references the fallback version (not the stale pinned one).
---ci---
project: orca
phase: 1
milestone: v0.15
status: execute
decisions:
- id: D-001
decision: Recompute TARBALL in the fallback branch immediately
after VERSION is reassigned, so grep/sha256sum/tar use the
fallback version's filename instead of the stale requested
version's.
rationale: Reproduced the exact user error ("no properly formatted
checksum lines found") by running grep -F "$TARBALL" SHA256SUMS
| sha256sum -c with a stale v0.14.2 tarball name against v0.12.18
SHA256SUMS. TARBALL is the only stale variable: ASSET_URL and
VERSION are correctly updated from API output, and SHA256SUMS_URL
derives from ASSET_URL. Single-line fix, minimal blast radius,
preserves the working non-fallback path.
confidence: 0.96
alternatives:
- lazy TARBALL via a function (over-engineering for one stale
assignment)
- move TARBALL= assignment past the fallback block (breaks
find_asset_url which needs the requested version's name
pre-walk)
lessons:
- When a fallback/walk mutates one variable (VERSION), audit every
variable derived from it (TARBALL) for the same mutation. The
user-facing info line at 167 constructed the name inline and
looked correct, masking that the variable itself was stale.
---/ci---
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.