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 first compatibility fixture targets Zeus v0.1.4 in docs/zeus-openapi-v0.1.4.json.

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.1.4 compatibility fixture in docs/zeus-openapi-v0.1.4.json
• 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,
• dry-run plan commands for bot create/lifecycle/reconcile actions,
• approval-backed execution for bot 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,
• local tests, repository checks, lifecycle smoke scripts, CI, and release smoke scripts.

Bot creation execution remains intentionally out of scope for the first release. Supported lifecycle, reconcile, and policy-limited tag rollout mutations require persisted dry-run plans, exact approval, preflight checks, postchecks, 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

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

olymp node check local-zeus
olymp zeus inventory local-zeus

Create a dry-run plan before any future mutation work:

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 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,
• bot creation remains dry-run only.

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

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>

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

Planning Docs

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