Skip to content

Getting Started

Welcome! This guide will help you set up Orrery and perform your first system triage in under 5 minutes.

Prerequisites

To try Orrery you only need:

  • Docker
  • An LLM API key. The examples below use Google Gemini because it has a free tier and is the quickest to start with, but Orrery is provider-agnostic — Anthropic Claude, OpenAI, and local Ollama models work too with no code changes. See Using a different LLM provider.

For local development (modifying agents or the core library) you'll additionally want Python 3.14+ and uv — see Local Development Setup below.

Quick Start (Docker — no clone required)

The fastest way to try Orrery is to pull the pre-built image from GHCR — no clone required.

Kick the tires (single container, ~30 seconds)

The quickest way to open the web UI and chat with the agent:

Start with the operator console

Once it is up, the web console has a Check my environment button that reports which integrations are actually wired — and what to configure when one is not. That is usually the fastest way past a first-run failure.

docker pull ghcr.io/bahalla/orrery:latest

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-api-key \
  ghcr.io/bahalla/orrery:latest

Open http://localhost:8000.

The image defaults to authentication on and the console off, so both variables are needed: without AUTH_ENABLED=false the server refuses to start (JWT_SECRET is required when JWT_ALGORITHM=HS256), and without ORRERY_WEB_CONSOLE_ENABLED=true there is no console to open.

Not using Gemini?

Swap the GOOGLE_API_KEY line for your provider's variables — e.g. -e MODEL_PROVIDER=anthropic -e MODEL_NAME=anthropic/claude-sonnet-4-20250514 -e ANTHROPIC_API_KEY=sk-ant-.... Full matrix in Using a different LLM provider.

What you get

The UI boots with in-memory session state. Tools that need external systems (Kafka, Kubernetes, Prometheus) will report that those systems aren't reachable — use the Full stack option below for the complete experience.

Anonymous and read-only

AUTH_ENABLED=false in the command above, and the compose demo profile below, which sets it too, make every caller an anonymous viewer: the agent can investigate, but RBAC refuses every change, so you won't see an approval card. make run-dev (ADK Dev UI) is also unauthenticated. Auth is on by default everywhere else. Do not expose an anonymous front door beyond localhost. To try the approval flow, use make demo, or make run-api with a token from make dev-token ROLE=operator. For a real deployment, see Production deployment → Step 4 and the Security guide.

Full stack (Kafka + Postgres + Prometheus + Loki + Alertmanager)

Download the compose file and start everything. Still no clone required:

curl -O https://raw.githubusercontent.com/BAHALLA/orrery/main/docker-compose.yml

GOOGLE_API_KEY=your-api-key docker compose --profile demo up -d

The compose file pulls ghcr.io/bahalla/orrery:latest by default.

Open http://localhost:8000.

Success

You now have a full autonomous DevOps stack running locally!

Pinning a specific version

Override the image tag to pin to a release (e.g. 0.17.0): 

ORRERY_IMAGE=ghcr.io/bahalla/orrery:0.17.0 \
  docker compose --profile demo up -d

Using a different LLM provider

Orrery routes every agent through LiteLLM, so you can switch backends with two environment variables — no code changes:

Variable Purpose
MODEL_PROVIDER Backend: gemini (default), anthropic, openai, ollama, …
MODEL_NAME Model identifier (the provider prefix is auto-added if you omit it)

Set those plus the matching API key for your provider. Whichever way you run Orrery, it's the same three variables:

MODEL_PROVIDER=gemini
MODEL_NAME=gemini-3.6-flash
GOOGLE_API_KEY=your-api-key   # aistudio.google.com/apikey

MODEL_PROVIDER=anthropic
MODEL_NAME=anthropic/claude-sonnet-4-20250514
ANTHROPIC_API_KEY=sk-ant-api03-...   # console.anthropic.com

MODEL_PROVIDER=openai
MODEL_NAME=openai/gpt-4o
OPENAI_API_KEY=sk-...   # platform.openai.com

MODEL_PROVIDER=ollama
MODEL_NAME=ollama/llama3
OLLAMA_API_BASE=http://localhost:11434   # ollama pull llama3 first

Apply them wherever you launch Orrery:

  • Single container — pass each as -e: 
    docker run --rm -p 127.0.0.1:8000:8000 \
  -e AUTH_ENABLED=false -e ORRERY_WEB_CONSOLE_ENABLED=true \
  -e MODEL_PROVIDER=anthropic \
  -e MODEL_NAME=anthropic/claude-sonnet-4-20250514 \
  -e ANTHROPIC_API_KEY=sk-ant-api03-... \
  ghcr.io/bahalla/orrery:latest
  • Full stack / Compose — put the same lines in your .env (Compose reads it automatically) or export them before docker compose --profile demo up -d.
  • Local development — add them to the root .env (see next section).

Planner note for non-Gemini backends

Planning is off by default (ORRERY_PLANNER=none). The builtin planner is the only Gemini-specific option — it uses Gemini's native thinking tokens and falls back to no planner (with a warning) on other providers. For a provider-agnostic reasoning trace, set ORRERY_PLANNER=plan_react.

For the complete provider matrix, key sourcing, context-caching caveats, and planner options, see General configuration → LLM Provider.

Local Development Setup

Follow these steps if you want to modify agents or contribute to the core library.

  1. Install Dependencies: 

    make install

  2. Configure Environment: We use a centralized environment file at the root of the workspace. 

    cp .env.example .env
# Edit .env: set MODEL_PROVIDER / MODEL_NAME and the matching API key.
# Defaults to Gemini (GOOGLE_API_KEY); see "Using a different LLM provider"
# above for Anthropic / OpenAI / Ollama.

  3. Start Infrastructure: Launch the supporting services (Kafka, Postgres, Prometheus). 

    make up

  4. Run the Orchestrator: 

    make run-api                  # API + web console on http://localhost:8000
make dev-token ROLE=operator  # in another terminal: a token to sign in with
    run-api is the product: authenticated, with the approval flow. For the unauthenticated ADK Dev UI instead (handy when working on an agent), run make run-dev.

Same port as the Docker demo

make run-api, make run-dev (ADK Dev UI) and docker compose --profile demo up -d all bind :8000. If you're running the Docker demo, the local targets will fail to start — docker compose down first, or change one of the ports.

A real incident in one command: make demo

make install           # once
cp .env.example .env   # once; set your LLM key in .env
make demo              # seeds the incident and opens the console on :8000

make demo starts Postgres, Kafka, kafka-exporter, Prometheus and Alertmanager, then breaks them on purpose (scripts/demo/seed.py):

  • a consumer group, orders-processor, 5,100 messages behind on the orders topic, with no active members;
  • its worker, orrery-demo-orders-worker, under a 16 MiB memory limit it can't start in. It is genuinely OOM-killed and restarted in a loop;
  • after ~30 s, the KafkaConsumerGroupLagHigh alert fires in Prometheus.

It prints an operator token to paste into the console. Then ask:

  1. "Why is the orders consumer lagging?" The Kafka, Docker and observability specialists work in parallel, and each tool call appears in the live trace as it runs.
  2. "Fix it." The fix is a mutation, so it stops at an approval card. Nothing changes until you click Approve.

Nothing is mocked: the agents diagnose what is really running, so this uses the LLM credentials in your .env. make demo-reset removes the topic, group and worker; make down stops the containers.

Your First Interaction

Once the platform is running, try these scenarios to see the agents in action:

1. Automated System Triage

Ask: "Is my cluster healthy?"

The "Magic": The orrery-assistant triggers a parallel health check across Kafka, K8s, Docker, and Elasticsearch. It correlates the data and synthesizes a single, high-level status report.

2. Targeted Investigation

Ask: "List all pods in the kube-system namespace."

The "Magic": The orchestrator identifies the intent and routes the request directly to the k8s-health specialist agent.

3. Guarded Operations (Safety)

Ask: "Scale the 'web-app' deployment to 3 replicas."

The "Magic": The agent identifies this as a mutating operation. It will present an interactive confirmation prompt before executing any changes.

This needs at least the operator role and a reachable Kubernetes cluster: run make run-api and sign in with a token from make dev-token ROLE=operator. On the anonymous Docker quick-start every caller is a viewer, so the request is refused instead. make demo leaves Kubernetes off, but its "Fix it." step shows the same approval card.

Explore Further