rubra-server 0.1.0

Server — REST API + live dashboard for Rubra.

Self-host a backend for your Rubra traces: browse them, run evaluations, and generate HTML reports from a browser — no notebook required.

Try the full stack now — zero cost, zero setup

Click Open in GitHub Codespaces above (or go to codespaces.new/pm1715/rubra-server). The devcontainer automatically:

• Clones rubra-sdk and rubra-deploy as sibling repos and installs everything
• Installs and starts Ollama with a small local model — no OpenAI key needed
• Installs kubectl, helm, and kind for testing the rubra-deploy Helm chart against a real (throwaway) Kubernetes cluster

Once it's ready:

# 1. Generate a real trace — a tool-calling agent, judged by a free local model
python examples/full_stack_demo.py

# 2. Start the server
uvicorn app.main:app --reload

Open the forwarded port-8000 URL for the dashboard, select the trace, and hit Evaluate — the judge-model field defaults to gpt-4o-mini but works with any litellm-supported model, including the free ollama/llama3.2:1b already running in the Codespace.

To also test the Kubernetes deployment for real:

cd ../rubra-deploy
./scripts/test-in-kind.sh

This builds the actual Dockerfile, loads it into a kind cluster, installs the Helm chart, and port-forwards it — a genuine deploy test with no registry or cloud cluster required.

Quickstart

Docker (recommended)

docker run -p 8000:8000 ghcr.io/pm1715/rubra-server:latest

Or with docker compose for persistent storage:

git clone https://github.com/pm1715/rubra-server
cd rubra-server
docker compose up

• Dashboard → http://localhost:8000
• API docs → http://localhost:8000/docs

From PyPI

pip install rubra-server
rubra-server

From source

pip install -e ".[dev]"
uvicorn app.main:app --reload

By default the server uses SQLite at .rubra/rubra.db and runs in open dev mode (no API key required).

Configuration

Copy .env.example to .env and adjust:

API

Full interactive docs at /docs (Swagger) and /redoc.

Dashboard

The / route serves a single-page dashboard: a trace list on the left, and on selection — trace metadata, span timeline, and an inline Evaluate button that runs any metric category and renders pass/fail results without leaving the page. The judge-model field next to it accepts any litellm model string, so goal metrics can run against a free local Ollama model instead of a paid API.

It polls /api/v1/traces every 30s, so traces produced by an instrumented agent elsewhere show up automatically.

Getting traces into the server

The server only reads traces — it doesn't instrument your agent. Point your app's storage at the same database, or use the SDK's Postgres/shared-SQLite backend:

import os
os.environ["RUBRA_DATABASE_URL"] = "postgresql://rubra:rubra@localhost:5432/rubra"

import rubra

@rubra.agent(task="Answer questions")
def my_agent(question: str) -> str:
    ...

As long as rubra-server points at the same RUBRA_DATABASE_URL, traces appear in the dashboard as soon as the agent finishes.

Security & Code of Conduct

This repo follows the same Security Policy and Code of Conduct as rubra-sdk.

License

Apache 2.0 — see LICENSE.