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 0.5.0, captured exactly from upstream commit ce9dfdfd7c9ea7dc367fd6c1cb15ab8be0d1ea95 in docs/zeus-openapi-v0.5.0.json. The retained v0.3.0 and v0.1.4 fixtures are legacy read-only contracts.

Goals

• Manage multiple Zeus instances without exposing Zeus directly to the public internet.
• Discover Zeus nodes, verify their /health, /ready, /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.
• Olymp will not integrate directly with Hermes or another agent harness in this compatibility step; Zeus remains the only bot-creation boundary.

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 0.5.0 mutation compatibility fixture in docs/zeus-openapi-v0.5.0.json, with v0.3.0 and v0.1.4 kept as legacy read-only fixtures
• 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,
• SQLite-backed operation event bus with in-process plugin subscribers,
• olymp doctor,
• olymp node add/list/check/remove,
• olymp zeus health/ready/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,
• event timeline inspection with olymp events list/tail,
• 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, authenticated GET /events, GET /runs/<run-id>/events, 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.5.0

olymp node check local-zeus
olymp zeus ready 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 the exact reviewed 0.5.0 expected_version. Health, inventory, and history remain available for versionless or legacy nodes, but execution rechecks the current registration and authenticated Zeus /ready response before any mutation. Zeus not_ready responses fail closed without recording a mutation attempt.

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 create-bot local-zeus \
  --bot-id kimi-coder \
  --template-id kimi-k3-coding-bot \
  --reason "prepare Kimi K3 coding 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

Configure KIMI_API_KEY and the optional KIMI_BASE_URL only on the Zeus host. Olymp sends the bot ID and kimi-k3-coding-bot template ID; it does not accept, persist, or forward provider credentials or harness configuration.

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>
olymp events list --limit 50
olymp events tail --run-id <run-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. New plans, runs, and Zeus mutation attempts also emit durable event-bus records that plugins can consume through olymp.events.subscribe_events(...).

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