orca/README.md

# 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](.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)

```bash
# 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:

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

### Build from source

```bash
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:

```bash
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](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](docs/cli.md) | CLI reference — every command, flag, and example |
| [docs/jobspec.md](docs/jobspec.md) | Jobspec reference — markdown frontmatter schema |
| [docs/ingress.md](docs/ingress.md) | Ingress guide — Traefik configuration |
| [docs/namespace.md](docs/namespace.md) | Namespace and path layout |
| [docs/install.md](docs/install.md) | Installation guide |
| [docs/security-scanning.md](docs/security-scanning.md) | Security scanning tools |

## Examples

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

## Development

```bash
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](.ciagent/ARCHITECTURE.md) for full
architecture details.

## License

MIT — see [LICENSE](LICENSE).