Jon Chery
4c2e59cf3f
Root cause: orca job run <example>.md failed with fork/exec: no such
file or directory on every example. Two compounding problems:
1. workloadToTaskSpecs (internal/cli/job.go:340) passed the entire
runtime.command string (e.g. "/usr/bin/httpd -f /etc/orca/web-app/
httpd.conf") as a single binary path to exec.Command, which then
looked for a file literally named "/usr/bin/httpd -f ..." and
failed. The v0.9 markdown parser stores command: as a raw string;
the legacy HCL path had separate command+args fields. Fix: add
splitCommand helper that splits on strings.Fields into binary+args,
with /bin/true fallback for empty commands.
2. The example commands referenced binaries that don't exist on a bare
Linux machine (/usr/bin/httpd, postgres, api-server, fluent-bit).
Fix: rewrite the 5 example runtime.command values to use /bin/sleep
3600 (long-running services) or /bin/echo (one-shot job) so they
run out-of-the-box. Each file has a Production substitution note
showing the real binary to use in deployment.
Verified: orca job run examples/full-stack/worker.md now succeeds
(exit 0). All 4 services (web-app, api, log-shipper, postgres) start
correctly (task started, pid assigned). 12 new unit tests pass
(splitCommand: 7 cases, workloadToTaskSpecs: 5 cases). All 5 example
jobspecs still parse + validate (gate C-20). make lint clean.
---ci---
project: orca
phase: 6
milestone: v0.10
status: execute
decisions:
- id: D-195
decision: split command string via strings.Fields in workloadToTaskSpecs
rationale: exec.Command expects binary path + args as separate elements;
the v0.9 markdown parser stores command: as a single string with no
args field (unlike legacy HCL). strings.Fields is dep-free and handles
multiple spaces/tabs. Shell quoting (single/double quotes inside the
command) is not handled — examples avoid sh -c with quoted strings.
confidence: 0.95
alternatives: [shellquote.Split from mvdan/sh (adds dependency)]
lessons:
- The v0.9 markdown jobspec path needs the same command+args split that
the legacy HCL path had via separate command/args fields. The parser
stores command: as a raw string; the CLI must split it before passing
to exec.Command.
- Example jobspecs should use /bin/sleep and /bin/echo (binaries that
exist on every Linux machine) so they run out-of-the-box. Descriptive
production commands belong in a comment block, not in runtime.command.
---/ci---
Orca
Offline/CLI-first orchestration engine inspired by HashiCorp Nomad, far simpler than Kubernetes.
Status
v0.9: Re-architecture Foundation — COMPLETE | v0.10: Docs & Install Hardening — IN PROGRESS
See .ciagent/ROADMAP.md for the full roadmap.
Pillars
- Simplicity — single binary, minimal dependencies
- AI-first — CLI designed for both humans and AI agents
- Offline-first — no cloud dependencies
- CLI-first — primary interface is the command line
- Security before features — NFRs ship before new functionality
- Bug fixes before features — stability is paramount
- NFRs before features — observability and auditability first
Quickstart
Install (1-liner)
# User-level install (binary at ~/.local/bin/orca, state at ~/.orca)
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/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/branch/main/scripts/install.sh | sudo bash -s -- --system
# Pin a specific version
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/main/scripts/install.sh | bash -s -- --version v0.9.1
# Dry-run: check what would be installed without writing
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/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/branch/main/scripts/install.sh | bash
# → "updated orca from v0.8.15 to v0.9.1"
Subcommands
| Command | Description | Since |
|---|---|---|
orca init |
Initialize local orca state (full bootstrap) | v0.6 |
orca version |
Print version info | v0.1 |
orca status |
Show orca daemon status (deprecated v0.9) | v0.1 |
orca job run |
Run a job from a spec file (.md/.yaml/.hcl) |
v0.1 |
orca job list |
List all jobs (--watch for streaming) |
v0.1 |
orca job stop |
Stop a running job | v0.1 |
orca job logs |
Show task output for a job | v0.1 |
orca node join |
Join a node (--type proxmox for SSH-push) |
v0.2 |
orca node leave |
Remove a node from the registry | v0.2 |
orca node list |
List all nodes (--watch for streaming) |
v0.2 |
orca node key-reset |
Reset SSH known_hosts entry for a node | v0.8 |
orca node capacity |
Manage node capacity (show/set/list) | v0.2 |
orca ns list |
List all namespaces | v0.9 |
orca ns create |
Create a namespace directory + ns.md | v0.9 |
orca ns delete |
Remove an empty namespace | v0.9 |
orca ns inspect |
Print effective chain, merged env, constraints | v0.9 |
orca ns validate |
Run cycle + missing-parent + schema checks | v0.9 |
orca doctor |
Run self-checks (cert/network/db/os/proxmox) | v0.2 |
orca audit list |
View audit log entries | v0.1 |
orca daemon |
Run the daemon (deprecated v0.9) | v0.1 |
orca cert |
Manage certificates (deprecated v0.9) | v0.2 |
See docs/cli.md for the full CLI reference with all flags and examples.
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/docker.md | Docker image 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
make test-race # Run tests with race detection
make lint # Run gofmt + go vet + shellcheck
make fmt # Format code
make security-scan # Run gosec + govulncheck + gitleaks
make verify-reqs # Assert ROADMAP ↔ REQUIREMENTS consistency
make changelog # Generate CHANGELOG.md from ---ci--- blocks
make release # Build + create Gitea release (VERSION required)
Architecture
See .ciagent/ARCHITECTURE.md for full architecture details.
License
MIT — see LICENSE.