Practical README

Nimbus-Orch

Last updated: 2026-07-09

nsc-orch-http is the Podman-facing HTTP controller for evidence-gated checkpoint, recover, and branch movement. It does not treat Podman access as authority.

Quick start Product page

Status: Private distribution

Podman • Go Read / write / ptr posture Executed inspect first No key in image

What it is

Podman controller

Small HTTP surface for checkpoint, recover, and branch movement against Podman targets.

Evidence gate

Write-class movement requires readiness, normalized target, allowlisted action, executed inspect, ownership posture, and pressure posture.

Containment posture

Unknown ownership, invalid claims, explicit zipproc requirements, and critical pressure route away from ordinary movement.

Read / write / ptr posture

read  -> inspect/report/status posture
write -> checkpoint/recover/branch/pause-class posture
ptr   -> roster/pointer/record-start control posture

Generic Zipproc remains per-executable:

zipproc run --exe ...

Nimbus-Orch does not turn that into arbitrary per-container execution.

Quick start

Run locally from the Go controller workspace:

go test ./cmd/nsc-orch-http
go run ./cmd/nsc-orch-http

Build the controller image:

docker build -t nimbus-orch:2026.1.0 .

The image is controller-only. It intentionally does not include Podman, does not mount the Podman socket, and does not carry host/container write authority by itself.

API overview

Read/report

GET  /podman/targets
GET  /podman/target/status?target=nsc-managed-app
GET  /podman/target/report?target=nsc-managed-app
POST /podman/target/report/record

Checkpoint

POST /podman/checkpoint/eval
POST /podman/checkpoint/take
GET  /podman/checkpoint/roster?target=nsc-managed-app

Recover

POST /podman/recover/eval
POST /podman/recover/start

Branch and preflight

POST /podman/preflight
POST /podman/branch/eval
POST /podman/branch/start

Example calls

curl -s 'http://127.0.0.1:8080/podman/target/report?target=nsc-managed-app'

curl -s -X POST http://127.0.0.1:8080/podman/checkpoint/eval \
  -H 'Content-Type: application/json' \
  -d '{"target":"nsc-managed-app","readiness":"ready","reason":"pre-update","checkpoint_id":"nsc-managed-app-001"}'

curl -s -X POST http://127.0.0.1:8080/podman/checkpoint/take \
  -H 'Content-Type: application/json' \
  -d '{"target":"nsc-managed-app","readiness":"ready","reason":"pre-update","checkpoint_id":"nsc-managed-app-001"}'

curl -s -X POST http://127.0.0.1:8080/podman/recover/start \
  -H 'Content-Type: application/json' \
  -d '{"target":"nsc-managed-app","readiness":"ready","reason":"pre-rollback","checkpoint_id":"nsc-managed-app-001"}'

Safety boundary

Ready does not mean safe forever.
Restore does not mean trust.
Recorded reports are process-local observations, not durable truth.
Roster means controller action history, not durable truth.
Unknown or invalid containers belong to Podman-specific zipproc containment posture.
Write-class Podman movement requires executed inspect posture first.
Supplying a Podman socket, privileged mode, or host write path is supplying the key to the kingdom.

Scope

This package is:

a Podman-facing controller for bounded checkpoint, recover, and branch movement
evidence-gated before write-class movement
explicit about read/write/ptr posture
suitable for private controlled deployment

This package is not:

a general orchestration platform
a Kubernetes scheduler
a malware scanner
a host-wide shell
generic zipproc run --exe
Copr per-executable runner
a container image that carries Podman authority by itself

Version

2026.1.0