rosen

README

Rosen

A Kubernetes-style control plane for AI agents.

Rosen lets you declare agents, models, and tools as YAML resources and have a controller continuously reconcile them toward a running state: the same desired-vs-actual control loop Kubernetes uses for containers, applied to open-source-model AI agents. It is built on Kubernetes (real CRDs + controller-runtime), with rosenctl and the SDK as the first-class interface.

---

Setup

Prerequisites: kind, kubectl, a container runtime with buildx, and Go 1.26+ (to install the CLI).

go install codeberg.org/DanielCastanho/rosen/cmd/rosenctl@v0.3.0   # add $(go env GOPATH)/bin to PATH
git clone https://codeberg.org/DanielCastanho/rosen.git && cd rosen  # CRDs, RBAC, webhook, examples

Install the control plane onto a fresh kind cluster (cert-manager, CRDs, RBAC, rosend, and the validating webhook):

./hack/install.sh --kind rosen

Already have a cluster? Drop --kind to install into your current context (kind, AKS, EKS, GKE, bare-metal); run ./hack/install.sh --help for the flags.

Examples

To deploy and run an agent, see examples/triage-agent/: a served agent on a self-hosted Ollama model, with conversational memory (Redis), semantic memory (pgvector), and an MCP tool. Its README walks through building, deploying, and running it.

---

Architecture

flowchart TB
    user(["you"])

    subgraph cp["Go control plane"]
        ctl["rosenctl<br/>apply · run · get · trace · delete · secret set"]
        subgraph rosend["rosend — controller-runtime manager"]
            arCtrl["AgentRun reconciler<br/>resolve refs · dispatch · poll"]
            adCtrl["AgentDeployment reconciler<br/>drive replicas · publish endpoint"]
        end
    end

    api[("Kubernetes API server<br/>Rosen CRDs + built-in Secret")]

    subgraph exec["execution paths"]
        job["one-shot Job (per run)<br/>ROSEN_REQUEST → /dev/termination-log"]
        served["served Deployment + Service<br/>POST /invoke (202) · GET /result/{trace}"]
    end

    subgraph agent["agent (python3 · rosen SDK)"]
        run["rosen.run — one-shot handler"]
        serve["rosen.serve — HTTP server<br/>/healthz · /invoke · /result"]
        model["ctx.model → Engine adapter"]
        tools["ctx.tools → Transport adapter<br/>(mock / http / mcp)"]
        memory["ctx.memory → Memory backend<br/>(remember / recall / history)"]
    end

    llm(["OpenAI-compatible endpoint<br/>vLLM · Ollama · hosted"])
    toolsrv(["tool server<br/>(MCP / HTTP)"])
    memstore[("memory store<br/>Redis · pgvector · FAISS")]

    user --> ctl --> api
    arCtrl -->|watch · resolve refs| api
    adCtrl -->|reconcile · own Deployment + Service| api
    arCtrl -->|template run| job --> run
    arCtrl -->|served run| served --> serve
    adCtrl -->|create + drive replicas| served
    arCtrl -.->|inject ROSEN_MODEL_* via secretKeyRef| job
    adCtrl -.->|inject ROSEN_MODEL_* via secretKeyRef| served
    run --> model --> llm
    serve --> model
    model -->|model-driven tool loop| tools
    model -->|session recall / remember| memory
    tools --> toolsrv
    run --> memory
    serve --> memory
    memory --> memstore
    arCtrl -->|write run status| api
    adCtrl -->|write observed status| api

License

AGPL-3.0.