Project: Orca

Vision

A minimalist, offline-first, CLI-first orchestration engine inspired by HashiCorp Nomad, prioritizing stability, security, and simplicity over feature richness.

Objective

Build a lightweight system to manage and execute workloads across a set of nodes, keeping complexity far below that of Kubernetes.

Requirements

CLI First: Primary interaction through a CLI tool.
Offline First: Functional without constant internet connectivity.
AI First: Designed to be easily discoverable and manageable by AI agents.
Stability & Security: Prioritize security fixes and bug fixes over new features.
Language: Written in Go 1.25+.
Simplicity: Minimalist implementation, avoiding the "K8s complexity trap".

Constraints

No web UI as a primary requirement.
Must not implement K8s-level complexity.
Feature development must move slowly to ensure stability.
Only CI system allowed: CoreCI (git.cloudinit.dev/coreci/coreci).
Gitea remote: git.cloudinit.dev/coreci/orca.

Clarified Decisions (D-series, full autonomy)

ID	Question	Decision	Rationale	Confidence
D-001	Single binary or multi-binary distribution?	Single binary	Simpler distribution; subcommands baked into one `orca` binary. Aligns with simplicity pillar.	0.95
D-002	Local state store technology?	modernc/sqlite (pure Go, CGO-free)	Cross-compile friendly, no CGO dependency, single file on disk, mature.	0.92
D-003	Inter-node communication?	Embedded HTTP (net/http) over loopback, mTLS for cross-node	No external RPC framework needed for v0.1. HTTP suffices.	0.85
D-004	Scheduling algorithm for v0.1?	Single-node only (no scheduling)	Multi-node scheduling is out of scope for v0.1. Tasks run on the node they're submitted to.	0.90
D-005	CLI output format?	Human-readable by default, `--json` flag for machine consumption	Serves both humans and AI agents.	0.95
D-006	Job/task definition format?	HCL or YAML in `.hcl`/`.yaml` files	Familiar to Nomad/HashiCorp users; simpler than JSON for humans.	0.88
D-007	Authentication?	mTLS for v0.1, token-based deferred	mTLS is the most secure default. Tokens can be added later if needed.	0.80
D-008	Container runtime?	Direct process execution (no container runtime) for v0.1	Avoids the Docker/container dependency. Pure process management.	0.85
D-009	Configuration file location?	`~/.orca/config.hcl` and `/etc/orca/orca.hcl`	Standard XDG-style paths.	0.90
D-010	Logging format?	Structured JSON via `log/slog`	Native Go 1.21+ slog, no external dependency.	0.95

Out of Scope

Full-blown Kubernetes-compatible API.
Complex cloud-provider integrations.
GUI-based management consoles.
Multi-node scheduling.
Container runtime integration.
Service mesh / sidecar injection.
Auto-scaling / horizontal pod autoscaler.

3.0 KiB Raw Blame History