docker run --rm -p 127.0.0.1:8000:8000 -e AUTH_ENABLED=false -e ORRERY_WEB_CONSOLE_ENABLED=true \
-e GOOGLE_API_KEY=your-key ghcr.io/bahalla/orrery:latest
Then open http://localhost:8000. Works with Gemini, Claude, OpenAI, or a local Ollama model.
This front door is anonymous, so every caller is a viewer: it can investigate but not change
anything. For the approval flow, run make demo, or make run-api with a token from
make dev-token ROLE=operator.
- Investigates, not just alerts. Consumer lag, pod state, logs and metrics are checked in
parallel and correlated in one answer, with every tool call shown as it runs.
- Asks the right person. Changes wait for approval from the verified person who asked: a
casual "ok", or a colleague's "approve", doesn't count.
- Injection-aware. Hostile text inside a log line or a pod annotation is neutralized where it
lands, not obeyed, because it is also the evidence being diagnosed.
- Cites your runbooks. Retrieved passages carry their source and their age, so a stale
procedure says it is stale.
- Closes the loop. On the triage path, a fix is verified, and retried a bounded number of
times if it didn't work.
Why Orrery
An alert tells you that something is wrong. Finding out what still means a human
opening five consoles at 03:00. Orrery gives you specialist agents — Kafka, Kubernetes,
Elasticsearch, Docker, Prometheus/Loki — coordinated by a root agent that runs them in
parallel, correlates what they find, and proposes or performs the fix.
The name is the design: an orrery is a mechanical model of the solar system. Specialists
orbit a coordinator, and every moving part is visible and accountable.
Beyond the approval gate and injection screening above, two more things make it safe enough
to point at production:
- Two orthogonal axes of control. RBAC answers who (viewer / operator / admin); an autonomy
level answers what this process may do (L2 read-only → L4 confirmed-destructive).
- An audit trail you can alert on. Every tool call, and every confirmation raised, decided,
refused or expired, is a structured log line and a Prometheus counter. Someone else trying to
approve your action pages on-call.
Quick start
The one-liner at the top runs the web console with in-memory sessions and whichever provider
you configured — Gemini, Claude, OpenAI, or a local Ollama model (no key needed). It is
anonymous and read-only (every caller is a viewer).
For the full local stack (Kafka, Postgres, Prometheus, Loki, Alertmanager) — still no clone
required, and just as anonymous. Add --profile elastic for Elasticsearch and Kibana:
curl -O https://raw.githubusercontent.com/BAHALLA/orrery/main/docker-compose.yml
GOOGLE_API_KEY=your-key docker compose --profile demo up -d
From source: make install && make up && make run-api, then make dev-token ROLE=admin for a
token to sign in with. make help lists every target.
See it handle an incident in a minute: make install && cp .env.example .env (add your LLM
key), then make demo. It breaks things on
purpose on the local stack: a consumer group 5,100 messages behind, because its worker is
OOM-killed in a loop. Then it opens the console. Ask "Why is the orders consumer lagging?",
then ask it to fix what it finds. Nothing is mocked: the agents find what is really there
(uses the LLM credentials in your .env). make demo-reset cleans up. The
Getting Started guide covers providers,
SSO, Slack and Google Chat.
What's in the box
| Agent | Tools | What it does |
|---|
| orrery-assistant | — | Root coordinator; single-turn incident triage; closed-loop remediation (act → verify → retry) |
| kafka-health | 24 | Brokers, topics, consumer lag, offset resets; Strimzi-aware |
| k8s-health | 26 | Pods, deployments, events, logs, rollbacks, resource usage; operator-aware |
| elasticsearch | 24 | Cluster, index and shard diagnostics, ILM, snapshots; ECK-aware |
| observability | 16 | Prometheus queries, Loki logs, Alertmanager silences |
| docker-agent | 17 | Container health, stats, logs, Compose projects |
| ops-journal | 10 | Notes, preferences and bookmarks that persist across sessions |
| slack-bot / google-chat-bot | — | Chat surfaces with Approve / Deny cards, same gate and RBAC |
Every agent runs standalone or composed under the coordinator, and every cross-cutting concern
is a plugin applied once to all of them.
Highlights
- Watch it work — answers stream in under a live trace of every specialist consulted and each
tool it runs, in the console, Slack and Google Chat alike.
- Bring your own tools, safely — connect any MCP server; its tools pass the same RBAC,
autonomy and approval gates, and anything you haven't classified is treated as destructive.
MCP servers →
- Acts as the person who asked — Kubernetes and Elasticsearch calls carry the verified user,
so their own permissions and audit logs apply on top of Orrery's.
Impersonation →
- Agents without a release — specialists are discovered from installed packages; admins
compose new ones from existing tools, or switch them off, from the console, live.
Adding an agent →
- Reads your runbooks, not just your clusters — opt-in retrieval over the docs your team wrote
(filesystem, git, Confluence → Elasticsearch BM25 or hybrid pgvector). Every passage cites its
source and its age. Knowledge retrieval →
- Deterministic triage workflow — a graph
Workflow fans out to all specialists, joins, records a
severity verdict, then routes to bounded remediation or a final report. Runs on a schedule with
make run-triage. ADR-003 →
- Cross-session memory — past incidents and resolutions are recalled on demand, with credentials
scrubbed on the way in and out. Memory →
- Long incidents don't hit the context wall — older turns are compacted into a digest for the
model while the full record stays intact for audit and replay.
- Any LLM provider — Gemini, Claude, OpenAI or Ollama via one env var; context caching and
safety settings applied automatically on Gemini.
- Six surfaces, one gate — web console (OIDC/PKCE SSO or JWT), CLI, ADK dev UI, Slack, Google
Chat, and A2A for other agents. The confirmation and RBAC rules are identical on every one; an
agent calling over A2A never approves, its user does.
How it fits together
Built on Google ADK. A chat-mode root agent owns the
conversation and delegates to specialists as tools; a separate graph workflow provides the
deterministic batch path. Guardrails, RBAC, autonomy, audit, metrics, tracing, injection screening,
credential redaction and output capping are ADK plugins registered once on the runner, so a new
agent inherits all of them by construction.
Read the architecture overview, the
ADRs, or the
enhancement proposals that record how each
piece came to be.
Background
Orrery was built in the open, and the reasoning behind most of it was written down as it
happened. Building AI Agents for DevOps
is a twelve-part series covering the design decisions — what was tried, what broke, and why the
code looks the way it does. Each part pairs with the reference docs for the same subsystem.
Two standalone pieces go wider than the series:
The agent gateway — one turn pipeline behind every surface
on how five surfaces share one gate, and
How to build AI agents — a practical guide
on the patterns that generalise beyond this codebase.
Contributing
Issues and pull requests are welcome — see CONTRIBUTING.md. Security reports go
through SECURITY.md, not the public tracker. make check runs the whole gate
(lint, types, ~2,200 Python tests, web console tests) and mirrors CI.
License
MIT.
