STELLA

---

🏠 What is STELLA?

STELLA is an open-source platform for building, deploying, and testing voice-enabled conversational AI agents. Deploy an agent, have a conversation, iterate — it's that simple.

You bring the agent logic. STELLA handles the audio/video streaming, orchestration, and infrastructure. Built with NestJS, React, a Python Agent SDK, LiveKit for WebRTC, and Kubernetes for on-demand agent orchestration.

✨ Key Features

• 🎙️ Voice & text conversations via WebRTC (LiveKit)
• ☸️ On-demand Kubernetes agent orchestration
• 🐍 Python Agent SDK with built-in STT/TTS pipeline
• 🤖 Multi-agent support (stella-v2, stella-light-agent, and custom agents)
• 🛡️ Expert Pool for safe handling of sensitive, high-stakes conversations
• 📋 Plan-driven conversation flows with state machine
• 🔐 Project & session management with role-based access
• 💬 Real-time transcript & event timeline
• 📊 Admin dashboard with live metrics
• 🚀 One-command deployment (./scripts/start-k8s.sh)

✅ Requirements

To run STELLA you need three things:

• Docker — OrbStack (recommended) or Docker Desktop on macOS, Docker Engine on Linux, or Docker via WSL2 on Windows
• An OpenAI API key — OpenAI is the default LLM provider (and powers the STT/TTS pipeline). Support for local models via Ollama and additional providers is on the way
• A LiveKit server — LiveKit Cloud (easiest) or self-hosted, for real-time voice/video

That's it. Kubernetes (OrbStack's built-in cluster or auto-installed K3s), kubectl, and PostgreSQL are provisioned automatically by the startup script — you don't install them yourself.

🚀 Quick Start

Two commands. That's it.

git clone https://github.com/c4dhi/STELLA.git && cd STELLA
./scripts/start-k8s.sh   # First run launches the setup wizard — no manual .env needed

Frontend at http://localhost:5173 · API at http://localhost:3000

New here? The Getting Started guide walks you through everything — prerequisites, LiveKit setup, and deploying your first agent.

🏗️ Architecture

LiveKit Server (external)  <-->  Agent Pods (Python)
         |                            |
   Frontend UI (React)  <-->  Backend API (NestJS)  <-->  PostgreSQL
         |
   STT/TTS Services (gRPC)

Everything runs inside a single Kubernetes cluster (OrbStack on macOS, K3s on Linux), deployed automatically by the startup script. Agent pods spin up on-demand per session and clean up after themselves.

📖 Documentation

Full docs live at c4dhi.github.io/STELLA.

	Section	What you'll find
🚀	Getting Started	Prerequisites, installation, first agent
🏗️	Architecture	System design and component deep-dive
🤖	Building Agents	Create your own conversational agents
📦	Agent SDK Reference	Python SDK API reference
🚢	Deployment	Production deployment guide
🤝	Contributing	How to get involved

🤝 Contributing

We'd love your help! Whether it's bug reports, feature ideas, docs improvements, or code — all contributions are welcome. Check out the Contributing Guide and Code of Conduct to get started.

💬 Community & Support

• GitHub Issues — Bug reports and feature requests
• Documentation — Guides, tutorials, and API reference

📚 Citation

If you use STELLA in your research, please cite it. GitHub's "Cite this repository" button (backed by CITATION.cff) generates APA and BibTeX entries. A permanent, versioned DOI will be minted via Zenodo with the first tagged release — see RELEASING.md.

📄 License

STELLA is released under the MIT License — © Universität St. Gallen (HSG) & University of Zurich (UZH). It runs on your own hardware and is free to use, modify, and redistribute. See NOTICE.md for third-party component attributions.