Olymp Orchestrator

Higher-level orchestration for brainx/zeus, the Zeus Hermes Orchestrator.

Olymp is planned as the control plane above Zeus: Hermes runs the bot runtime, Zeus renders and supervises Hermes bot profiles on one host, and Olymp manages many Zeus nodes, policies, rollout plans, health, evidence, and operator workflows from one secure interface.

flowchart TD
  O["Olymp control plane"] --> Z1["Zeus node: workspace A"]
  O --> Z2["Zeus node: VPS staging"]
  O --> Z3["Zeus node: production host"]
  Z1 --> H1["Hermes bot profiles"]
  Z2 --> H2["Hermes bot profiles"]
  Z3 --> H3["Hermes bot profiles"]

Loading

Upstream Zeus

Olymp is a companion control plane for brainx/zeus. It does not vendor or replace Zeus. Operators run Zeus from the upstream project on each node, keep the Zeus API loopback-only, and register those nodes in Olymp for inventory, planning, approved lifecycle execution, audit trails, and evidence export.

The current mutation compatibility target is Zeus v0.3.0, captured exactly from the upstream tag in docs/zeus-openapi-v0.3.0.json. The retained docs/zeus-openapi-v0.1.4.json fixture is transitional and legacy read-only.

Goals

• Manage multiple Zeus instances without exposing Zeus directly to the public internet.
• Discover Zeus nodes, verify their /health, /doctor, template, bot, status, log, inspect, and reconcile surfaces, and track compatibility against Zeus' OpenAPI contract.
• Provide a professional CLI and API first, with a dashboard once the backend contract is stable.
• Coordinate bot lifecycle operations across hosts with explicit approvals, dry runs, audit logs, rollback notes, and evidence capture.
• Keep secrets out of source, UI bundles, logs, examples, and generated artifacts.
• Reuse the existing DigitalOcean VPS as the staging environment after live inventory and access checks confirm it is still available.
• Match Zeus' operational style: Python 3.11+, small reviewable modules, strict checks, systemd samples, OpenAPI, release notes, and GitHub release artifacts.

Non-Goals

• Olymp will not replace Hermes or Zeus.
• Olymp will not make Zeus' local API internet-facing.
• Olymp will not run arbitrary shell commands as a generic remote execution product in the MVP.
• Olymp will not store provider credentials by default. Bot/provider secrets should stay in Zeus/Hermes host-specific configuration or an approved secret store.

Planned Shape

• Package: olymp-orchestrator
• CLI: olymp
• Local API: 127.0.0.1:4321 by default
• State: SQLite for the local control plane, with append-only JSONL audit logs
• Integration: typed Zeus client checked against the Zeus v0.3.0 mutation compatibility fixture in docs/zeus-openapi-v0.3.0.json, with v0.1.4 kept only as a transitional legacy read-only fixture
• Deployment: systemd service, optional Caddy HTTPS front door for the Olymp UI/API, Zeus nodes kept loopback-only behind local agents or SSH/mTLS tunnels

Current MVP

The repository now includes the first CLI/API foundation:

• stdlib Zeus API client with API-key handling, strict JSON/content-type checks, response-size limits, and URL guardrails,
• SQLite Zeus node registry,
• append-only redacted audit log,
• olymp doctor,
• olymp node add/list/check/remove,
• olymp zeus health/doctor/templates/bots/inventory/history,
• dry-run plan commands for bot create/lifecycle/reconcile actions,
• approval-backed execution for bot create, lifecycle, and reconcile plans,
• configurable local policy loaded from $OLYMP_POLICY_FILE or $OLYMP_STATE_DIR/policy.toml,
• persisted plan/run inspection commands,
• redacted local evidence export,
• loopback-only Olymp API with GET /health and authenticated GET /doctor, GET /nodes, GET /nodes/<node-id>/health, and GET /nodes/<node-id>/inventory, plus paginated GET /nodes/<node-id>/bots/<bot-id>/history, and authenticated POST /plans/create-bot,
• local tests, repository checks, lifecycle smoke scripts, CI, and release smoke scripts.

Supported bot creation, lifecycle, reconcile, and policy-limited tag rollout mutations require persisted dry-run plans, exact approval, preflight checks, postchecks, durable mutation attempts, run records, and audit coverage.

Quick Start

python3 -m venv .venv
. .venv/bin/activate
pip install -e .
cp .env.example .env

olymp doctor
OLYMP_API_KEY=change-me sh scripts/start.sh

olymp doctor emits a structured readiness report and exits nonzero when a check fails. The public /health route remains a liveness check; authenticated /doctor returns HTTP 503 when Olymp is not ready.

Register a loopback Zeus node:

export ZEUS_API_KEY=change-me
olymp node add local-zeus \
  --name "Local Zeus" \
  --base-url http://127.0.0.1:4311 \
  --api-key-env ZEUS_API_KEY \
  --expected-version 0.3.0

olymp node check local-zeus
olymp zeus inventory local-zeus
olymp zeus history local-zeus coder --limit 50 --before 100

Bot history is returned newest first. Pass the previous response's next_before value to --before to fetch the next page.

Mutation plans require every target node to declare a supported 0.3.N expected_version, where N is a nonnegative integer. Health, inventory, and history remain available for versionless or legacy nodes, but execution also rechecks the current registration before any Zeus request.

Create and exactly approve a normal bot creation plan:

olymp plan lifecycle local-zeus coder --action restart \
  --reason "roll updated config" \
  --rollback-note "stop the bot if health checks fail"

olymp plan create-bot local-zeus \
  --bot-id coder-next \
  --template-id coding-bot \
  --reason "prepare next bot"

olymp plan execute <plan-id> --approve <plan-id>

olymp plan rollout-lifecycle coder --action restart \
  --tag staging \
  --reason "roll updated config across staging" \
  --rollback-note "stop unhealthy bots" \
  --retry-limit 1

Local Policy Defaults

Olymp applies conservative local policy before creating mutation plans:

• mutation plans require --reason,
• bot.restart requires --rollback-note,
• max_parallel is limited to 1,
• nodes tagged production are denied by default,
• normal bot.create is allowed, while bot.replace and bot.replace_stop are denied unless explicitly added to allowed_actions.

These defaults are intentionally strict for the alpha release. Invalid policy files fail closed.

Replacement planning uses --replace; adding --stop-existing selects the higher-risk bot.replace_stop action and is invalid without --replace. Execution sends one idempotent Zeus request and performs one inventory postcheck. An indeterminate transport outcome is recorded and is never automatically repeated; inspect Zeus and create a fresh plan. No archive/delete automation is included.

Inspect and execute supported lifecycle/reconcile plans:

olymp plan list
olymp plan show <plan-id>
olymp plan execute <plan-id> --approve <plan-id>
olymp run list
olymp run show <run-id>
olymp run resume <run-id> --approve <plan-id>

An approval can claim its plan only once, preventing concurrent or repeated Zeus mutations. Failed rollouts continue through run resume; each failed run can be resumed once and produces a new run record if another retry is needed. When upgrading existing state, legacy plans and runs are conservatively marked as consumed; create a fresh plan before making another change.

Export a redacted local evidence bundle:

olymp evidence export --include-audit

Stack Benchmark

Use scripts/benchmark_stack.py to capture a small Olymp/Zeus/Hermes latency snapshot. It prints a human summary and JSON output, and it reads provider keys only from private environment/profile files.

python3 scripts/benchmark_stack.py --skip-hermes

For the live Deepseek profile setup and sample config, see Stack benchmark.

Verification

sh scripts/test.sh
sh scripts/repo_check.sh
sh scripts/verify_lifecycle.sh

The lifecycle verifier uses temporary state by default. If its configured state already belongs to a running managed instance, it refuses the check and leaves that instance unchanged. Concurrent managed background starts are serialized; while one start is in progress, other attempts exit nonzero without replacing its PID metadata. Start-lock ownership is atomically published, and startup health is tied to the new process instance so an unrelated service on the configured port cannot be mistaken for Olymp.

Planning Docs

• Project plan
• Threat model
• Stack benchmark
• Staging runbook
• Backup and restore