omnara 1.3.0

Omnara Agent Dashboard - MCP Server and Python SDK

Omnara - Talk to Your AI Agents from Anywhere! 🚀

Ever wished you could peek into what your AI coding assistants are doing? Or help them when they get stuck? That's exactly what Omnara does!

What is Omnara?

Omnara is an open-source platform that lets you communicate with all your AI agents - Claude Code, Cursor, GitHub Copilot, and more - through one simple dashboard. No more wondering what your AI is up to or missing its questions!

The Magic ✨

• See Everything: Watch your AI agents work in real-time, like having a window into their minds
• Jump In Anytime: When your agent asks "Should I refactor this?" or "Which approach do you prefer?", you'll see it instantly and can respond
• Guide Your AI: Send feedback and corrections while your agent is working - it'll see your messages and adjust course
• Works Everywhere: Whether you're on your phone, tablet, or another computer, you can check in on your agents
• One Dashboard, All Agents: Stop juggling between different tools - see all your AI assistants in one place

Built on MCP (Model Context Protocol)

We use the Model Context Protocol to make this all work seamlessly. Your agents can talk to Omnara, and Omnara talks to you.

Project Architecture

Core Components

omnara/
├── backend/          # Web dashboard API (FastAPI)
├── servers/          # Agent write operations server (MCP + REST)
├── shared/           # Database models and shared infrastructure
├── omnara/           # Python package directory
│   └── sdk/          # Python SDK for agent integration
├── cli/              # Node.js CLI tool for MCP configuration
├── scripts/          # Development and utility scripts
└── webhooks/         # Webhook handlers

System Architecture

1. Backend API (backend/)

   • FastAPI application serving the web dashboard
   • Handles read operations and user authentication via Supabase
   • Manages API key generation and user sessions

2. Servers (servers/)

   • Unified server supporting both MCP and REST protocols
   • Processes all write operations from AI agents
   • Implements JWT authentication with optimized token length

3. Shared Infrastructure (shared/)

   • Database models and migration management
   • Common utilities and configuration
   • Ensures consistency across all services

Data Flow

AI Agents → MCP/REST Server (Write) → PostgreSQL ← Backend API (Read) ← Web Dashboard

Billing & Monetization (Optional)

Omnara includes optional Stripe integration for SaaS deployments:

• Free Tier: 20 agents per month
• Pro Tier ($9/mo): Unlimited agents
• Enterprise Tier ($500/mo): Unlimited agents + Teams, dedicated support, SLA (coming soon)

Billing is only enforced when explicitly configured with Stripe keys.

Development Setup

Prerequisites

• Python 3.12
• PostgreSQL
• Make (for development commands)

Quick Start

1. Clone the repository

   git clone <repository-url>
   cd omnara
   

2. Set up Python environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies and development tools

   make dev-install          # Install all Python dependencies
   make pre-commit-install   # Set up code quality hooks
   

4. Generate JWT keys for agent authentication

   python scripts/generate_jwt_keys.py
   

5. Configure environment variables Create .env file in the root directory (see Environment Variables section)

6. Initialize database

   cd shared/
   alembic upgrade head
   cd ..
   

7. Run the services

   # Terminal 1: Unified server (MCP + REST)
   python -m servers.app
   
   # Terminal 2: Backend API
   cd backend && python -m main
   

Development Commands

# Code quality
make lint              # Run all linting and type checking
make format            # Auto-format code
make pre-commit-run    # Run pre-commit on all files

# Testing
make test              # Run all tests
make test-sdk          # Test Python SDK
make test-integration  # Run integration tests (requires Docker)

# Database migrations
cd shared/
alembic revision --autogenerate -m "Description"  # Create migration
alembic upgrade head                              # Apply migrations

Code Quality

The project maintains high code quality standards through automated tooling:

• Ruff for Python linting and formatting
• Pyright for type checking
• Pre-commit hooks for automatic validation
• Python 3.12 as the standard version

Environment Variables

Required Configuration

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/omnara

# Supabase (for web authentication)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key

# JWT Keys (from generate_jwt_keys.py)
JWT_PRIVATE_KEY='-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----'
JWT_PUBLIC_KEY='-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----'

# Optional
ENVIRONMENT=development
API_PORT=8000
MCP_SERVER_PORT=8080

For AI Agent Developers

Getting Started

1. Sign up at the Omnara dashboard
2. Generate an API key from the dashboard
3. Configure your agent with the API key
4. Use either MCP protocol or REST API to interact

Available Tools/Endpoints

• log_step: Log progress and receive user feedback
• ask_question: Request user input (non-blocking)
• end_session: Mark agent session as completed

Integration Options

1. MCP Protocol (for compatible agents)

   {
     "mcpServers": {
       "omnara": {
         "url": "http://localhost:8080/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_API_KEY"
         }
       }
     }
   }
   

2. REST API (for direct integration)

   • POST /api/v1/steps
   • POST /api/v1/questions
   • POST /api/v1/sessions/end

3. Python SDK (available on PyPI)

   pip install omnara
   

Database Management

Working with Migrations

cd shared/

# Check current migration
alembic current

# Create new migration after model changes
alembic revision --autogenerate -m "Add new feature"

# Apply pending migrations
alembic upgrade head

# Rollback one migration
alembic downgrade -1

Important: Always create migrations when modifying database models. Pre-commit hooks enforce this requirement.

Contributing

We welcome contributions to this open-source project. Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and ensure code quality checks pass
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Support

• Issues: Report bugs or request features via GitHub Issues
• Discussions: Join the conversation in GitHub Discussions
• Documentation: Check the project documentation for detailed guides

License

Open source and free to use! Check the LICENSE file for details.