orca/README.md

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

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

```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/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](docs/cli.md) for the full CLI reference with all flags and examples.

## 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/docker.md](docs/docker.md) | Docker image 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
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](.ciagent/ARCHITECTURE.md) for full architecture details.

## License

MIT — see [LICENSE](LICENSE).