convez.ai
MCP Server
mifunedev

orchestra

mifunedev/orchestra

Ver no GitHub
BomPluginScore · de 0 a 100

Steerable Harnesses for DeepAgents — Orchestra🪶

Instalação

$npx convez-ai mifunedev/orchestra

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
18
Forks
1
Acompanhando
1
Saúde
87%
Último commit
há 1 mês
Versão
v4.0.0
Issues abertas
22
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

Steerable Harnesses for DeepAgents

License DCO

Open-source AI agent orchestration platform built on LangGraph and powered by the MCP & A2A protocols.

Self-host for free or let us deploy it for you. Your agents, your data, your infrastructure.


🚀 Deployment Options

OptionBest ForGet Started
Community (Free)Developers, self-hostingdocker pull ghcr.io/ruska-ai/orchestra:latest
Managed CloudTeams wanting conveniencechat.ruska.ai
EnterpriseOrganizations needing SSO, compliance, SLAContact Us

📖 Table of Contents

This project includes tools for running shell commands and Docker container operations. For detailed information, please refer to the following documentation:

🐳 Docker Deployment (GHCR)

We publish the backend image to GitHub Container Registry (GHCR). For the full Docker/Docker Compose deployment guide (env setup, services, migrations, troubleshooting), jump to Docker Deployment details.

docker pull ghcr.io/ruska-ai/orchestra:latest

📋 Prerequisites

  • Docker Installed
  • Python 3.11 or higher
  • Access to OpenAI API (for GPT-4o model) or Anthropic API (for Claude 3.5 Sonnet)

🛠️ Development

Quick Reference

CommandDescription
make devStart backend server (port 8000)
make dev.workerStart TaskIQ worker
make testRun all backend tests
make formatFormat code with Ruff
make seeds.userSeed default users
make migrate.upApply all pending migrations

For all commands, see backend/Makefile.

  1. Environment Variables:

    Create a .env file in the root directory and add your API key(s):

    # Backend
    cd <project-root>/backend
    cp .example.env .env
    
    # Frontend
    cd <project-root>/frontend
    cp .example.env .env
    

    Ensure that your .env file is not tracked by git by checking the .gitignore:

  2. Start Docker Services

    Below will start the database service.

    cd <project-root>
    docker compose up postgres
    

Dockerized Dev Stack

For containerized local development with hot reload, the whole stack (app, worker, postgres, redis, minio, ollama, search_engine) runs from the single infra/docker-compose.yml. The frontend runs on the host (cd frontend && npm run dev).

cd <project-root>
make dev.docker.up        # docker compose -f infra/docker-compose.yml up --build -d

Useful endpoints while debugging:

  • Backend API: http://localhost:8000/docs
  • Frontend (host): http://localhost:5173

Tail the main service logs in one stream:

make dev.docker.logs
  1. Setup Server Environment

    cd <project-root>/backend
    make dev
    

    Assumes you're using astral uv.

    cd <project-root>/backend
    uv venv
    source .venv/bin/activate
    uv sync
    bash scripts/dev.sh
    
  2. Setup Client Environment

    # Change Directory
    cd <project-root>/frontend
    
    # Install
    npm install
    
    # Run
    npm run dev
    

Database Migrations

This project uses Alembic for database migrations. Here's how to work with migrations:

Initial Setup

  1. Create the database (if not exists):

    cd backend
    alembic upgrade head
    
    python -m seeds.user_seeder
    
  2. Create new

    alembic revision -m "description_of_changes"
    
    ### Appliy Next
    alembic upgrade +1
    
    ### Speicif revision
    alembic upgrade <revis_id>
    
    ### Appliy Down
    alembic downgrade -1
    
    ### Appliy Down
    alembic downgrade <revis_id>
    
    ### History
    alembic history
    

Run Playwright MCP Locally

  1. Start Ngrok on port 8931

    ngrok http 8931
    
  2. Run MCP server

    npx @playwright/mcp@latest \
    --port 8931 \
    --executable-path $HOME/.cache/ms-playwright/chromium-<version>/chrome-linux/chrome \
    --vision
    

🤝 Integrations

🗺️ Roadmap

Stay up to date on Discord. Full release history in Changelog.md.

March 2026

FeatureCategoryStatus
Human-In-The-LoopAgent Control🔵 Planned

February 2026

FeatureCategoryStatus
Search ThreadsUX✅ Shipped
Migrate Memories SeederData✅ Shipped
Docs Agent GuidanceDocs🟡 In Progress
RLM SkillSkills✅ Shipped
Frontend Schedule RefactorScheduling✅ Shipped

January 2026

FeatureCategoryStatus
Distributed Workers (TaskIQ)Infra✅ Shipped
Public AgentsAgents✅ Shipped
File Tree SidebarUX✅ Shipped
AWS Model SupportIntegrations✅ Shipped
Shareable Thread LinksUX✅ Shipped
Subagent Tool CallsUX✅ Shipped
User Default SettingsSettings✅ Shipped
Speech DictationUX✅ Shipped

See Changelog.md for the full release history.


🏢 Enterprise

For organizations needing managed deployment, compliance, or dedicated support:

FeatureDescription
SSO/SAMLIntegrate with your identity provider
Audit LoggingComprehensive logs for compliance
Air-Gapped DeploymentRun in isolated environments
Priority SupportSLA-backed response times
Custom IntegrationsConnect to your internal tools

We partner with you to deploy Orchestra inside your infrastructure. Contact us to discuss your requirements.


🐳 Docker Deployment (GHCR / Docker Compose)

This section covers deploying the Orchestra backend using Docker. For local development, see the sections above.

📋 Prerequisites

  • Docker installed
  • Docker Compose installed
  • Access to AI provider API keys (OpenAI, Anthropic, etc.)

🚀 Quick Start

Using Pre-built Image

Pull the latest image from GitHub Container Registry:

docker pull ghcr.io/ruska-ai/orchestra:latest

1. Environment Setup

Create a .env.docker file in the backend/ directory:

cd backend
cp .example.env .env.docker

Update the following values for Docker networking:

# Database - use container name instead of localhost
POSTGRES_CONNECTION_STRING="postgresql://admin:test1234@postgres:5432/orchestra?sslmode=disable"

# Tools - use container names for internal services
SEARX_SEARCH_HOST_URL="http://search_engine:8080"

2. Start Services

From the project root directory:

# Start database and backend
docker compose up postgres orchestra

# Or start all services
docker compose up

3. Verify Deployment

The API will be available at http://localhost:8000

  • API Docs: http://localhost:8000/docs
  • Health Check: http://localhost:8000/health

🧩 Docker Compose Services

ServicePortDescription
orchestra8000Backend API
postgres5432PostgreSQL with pgvector
minio9000/9001S3-compatible file storage
search_engine8080SearXNG search engine
ollama11434Local LLM inference (requires GPU)
redis6379Redis message broker (for workers)
worker-TaskIQ worker (no exposed port)

🧱 Docker Compose Example

services:
    # PGVector
    postgres:
        image: pgvector/pgvector:pg16
        container_name: postgres
        environment:
            POSTGRES_USER: admin
            POSTGRES_PASSWORD: test1234
            POSTGRES_DB: postgres
        ports:
            - "5432:5432"

    # Server (use pre-built image or build locally)
    orchestra:
        image: ghcr.io/ruska-ai/orchestra:latest
        container_name: orchestra
        env_file: .env.docker
        ports:
            - "8000:8000"
        depends_on:
            - postgres

🏗️ Build Commands

Build with Script (Recommended)

The build script copies the Docker deployment README into the image and handles tagging:

# From project root
bash backend/scripts/build.sh

# Or with custom tag
bash backend/scripts/build.sh v1.0.0

Build with Docker Compose

docker compose build orchestra

Manual Build

# Copy README first, then build (Dockerfile lives in infra/)
cp infra/README.md backend/README.md
docker build -t orchestra:local -f infra/backend.Dockerfile backend

⚙️ Environment Variables

Application Config

VariableDescriptionDefault
APP_ENVEnvironment (development/production)development
APP_LOG_LEVELLogging levelDEBUG
APP_SECRET_KEYApplication secret key-
JWT_SECRET_KEYJWT signing key-
USER_AGENTUser agent string for requestsruska-dev
TEST_USER_IDTest user UUID-

Database

VariableDescriptionDefault
POSTGRES_CONNECTION_STRINGPostgreSQL connection string-

AI Providers (at least one required)

VariableDescriptionDefault
OPENAI_API_KEYOpenAI API key-
GROQ_API_KEYGroq API key-
ANTHROPIC_API_KEYAnthropic API key-
XAI_API_KEYxAI API key-
OLLAMA_BASE_URLOllama server URL-

Tool Config

VariableDescriptionDefault
SEARX_SEARCH_HOST_URLSearXNG search endpointhttp://localhost:8080
TAVILY_API_KEYTavily search API key-

Distributed Workers (Optional)

VariableDescriptionDefault
REDIS_URLRedis connection for task queue-
DISTRIBUTED_WORKERSEnable distributed worker modefalse

Note: When enabled, run the worker process separately: make dev.worker

Storage

VariableDescriptionDefault
MINIO_HOSTMinIO/S3 host URL-
S3_REGIONS3 region-
ACCESS_KEY_IDS3 access key-
ACCESS_SECRET_KEYS3 secret key-
BUCKETS3 bucket nameenso_dev

🗄️ Database Migrations

Run migrations inside the container:

# Using docker compose exec
docker compose exec orchestra alembic upgrade head

# Or run migrations before starting
docker compose run --rm orchestra alembic upgrade head

🚢 Production Considerations

Security

  • Generate strong values for APP_SECRET_KEY and JWT_SECRET_KEY
  • Use SSL/TLS termination (nginx, traefik, etc.)
  • Restrict database access to internal networks
  • Never expose .env files

Performance

  • Configure appropriate resource limits in docker-compose.yml
  • Use a reverse proxy for load balancing
  • Enable PostgreSQL connection pooling for high traffic

Dockerfile Features

The Dockerfile uses a multi-stage build:

  1. Builder Stage: Installs dependencies, compiles Python to bytecode (.pyc)
  2. Runtime Stage: Ships only compiled bytecode for smaller image size

Note: Migration files (.py) are preserved since Alembic requires source files.

🧰 Troubleshooting

Container won't start

# Check logs
docker compose logs orchestra

# Verify environment file exists
ls -la backend/.env.docker

Database connection failed

# Ensure postgres is running
docker compose ps postgres

# Check postgres logs
docker compose logs postgres

Port already in use

# Check what's using the port
lsof -i :8000

# Or change the port mapping in docker-compose.yml
ports:
  - "8001:8000"  # Map to different host port
Ver o original no GitHub

Bom para

Relacionados