Skip to content

Orrery

An on-call agent that investigates before it acts.

When an alert fires, Orrery's specialists for Kafka, Kubernetes, Prometheus/Loki, Elasticsearch and Docker investigate in parallel, read your runbooks, propose a fix, and wait for your approval before touching anything. Approval comes from the verified person who asked, and hostile text in logs or annotations is neutralized, not obeyed. Built on Google ADK, open source under MIT.

Asking why a Kafka consumer group is lagging: Orrery consults the Kafka and Docker specialists in parallel, streams their tool calls live, finds the worker OOM-killed in a loop, and proposes raising its memory limit — which waits on an approval card until the user approves.

Specialists consulted in parallel, every tool call visible, and nothing changes until you approve. make demo runs this incident for real.

Pick your path

  • I want to try it

    Run the full stack locally in Docker in under 5 minutes — Kafka, Postgres, Prometheus, and the orchestrator ready to go.

    Quick start with Docker

  • I want to deploy it

    Helm chart, multi-replica Postgres sessions, HPA, rolling updates, and observability scrape targets.

    Production deployment

  • I want to extend it

    Add your own specialist agent, wire it into the orchestrator, and ship it behind the same RBAC + guardrails.

    Adding a new agent

  • I want a chat surface

    Bring the agents into Slack or Google Chat with interactive Approve / Deny cards and email/user-ID RBAC.

    Integrations overview

Architecture Overview

The platform follows a Coordinator-Specialist pattern. A root orchestrator analyzes user intent and delegates to specialized agents. Cross-cutting concerns like safety, observability, and resilience are handled globally via a plugin system.

graph LR
    subgraph Frontends
        direction TB
        WEB[Web UI / CLI]
        SLACK[Slack]
        GCHAT[Google Chat]
    end

    subgraph Orchestrator
        ROOT[Orrery Chat]
    end

    subgraph Specialists
        direction TB
        KAFKA[Kafka Agent]
        K8S[K8s Agent]
        OBS[Observability]
        ES[Elasticsearch]
        DOCKER[Docker Agent]
        JOURNAL[Ops Journal]
        TRIAGE[Incident Triage]
    end

    subgraph Plugins
        direction TB
        P1[RBAC & Guardrails]
        P2[Metrics & Audit]
        P3[Memory & Resilience]
    end

    WEB --> ROOT
    SLACK --> ROOT
    GCHAT --> ROOT

    ROOT --> KAFKA
    ROOT --> K8S
    ROOT --> OBS
    ROOT --> ES
    ROOT --> DOCKER
    ROOT --> JOURNAL
    ROOT --> TRIAGE

    ROOT -.-> P1
    ROOT -.-> P2
    ROOT -.-> P3

Jump to a topic

  • Agents overview

    What's in the box — every agent, its tools, and the role each tool requires.

  • Guardrails & RBAC

    Three risk tiers, three roles, and how the confirmation gate works end-to-end.

  • Security & auth

    JWT-authenticated HTTP front door, claim-to-role mapping, and the SecretsManager for mounted Kubernetes Secrets.

  • Cross-session memory

    Let agents recall past incidents, resolutions, and team preferences.

  • Knowledge retrieval

    Index your runbooks, postmortems and ADRs so the agent answers from what your team wrote — with a citation and a document age.

  • Observability

    Prometheus metrics, OpenTelemetry traces, and log↔trace correlation — with a one-command Grafana stack.

  • Runbooks

    Operating Orrery itself: the first five minutes, escalation, and a page per alert.

  • Troubleshooting

    Common errors across every surface with pointers to the fix.

Core Philosophy

  1. Safety First: No destructive tool executes without verified human confirmation.
  2. Autonomous Investigation: Agents run diagnostics in parallel, mimicking an SRE's thought process.
  3. Closed-Loop Remediation: Actions are always followed by verification and retry loops.
  4. Observable by Design: Every interaction is instrumented with Prometheus metrics, OpenTelemetry traces, and audit logs.

Project Structure

Component Path Description
core core/ Shared library: agent factories, plugin system, validation, and base configurations.
agents agents/ Specialist agent implementations (Kafka, K8s, Docker, etc.).
infra infra/ Local diagnostic stack (Prometheus, Loki, Kafka, Grafana).
roadmap docs/enhancements/ Ongoing development and enhancement proposals (AEP).

Background: how this was built

The reference pages above describe what Orrery does. Building AI Agents for DevOps is a twelve-part series on why it does it that way — the decisions, the dead ends, and the rewrites behind each subsystem. Every part maps onto a page in these docs.

Post Reference page
1 · Why and how I designed the architecture Design patterns · Agents overview
2 · From terminal to Slack Slack
3 · RBAC — who can do what ADR-001: RBAC · Guardrails & RBAC
4 · Prometheus metrics Observability
5 · Sub-agents vs AgentTool ADR-002: Agent composition
6 · Security hardening Security · Guardrails
7 · ADK plugins and async tools Design patterns
8 · Agent evaluations Evaluations
9 · Google Chat integration Google Chat
10 · Fixing the approve handshake across sub-agents Guardrails & confirmation
11 · Adding planning mode with ADK planners Design patterns
12 · Distributed tracing with OpenTelemetry Observability

Two standalone pieces go wider than the series: The agent gateway on how five surfaces share one gate, and How to build AI agents on the patterns that generalise beyond this codebase.