orchestra

RCHESTRA

Steerable Harnesses for DeepAgents

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

📖 Table of Contents

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

• Tools Documentation
• Docker Deployment (GHCR / Docker Compose)

🐳 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

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 backend, frontend, worker, and supporting services can all run under docker-compose.dev.yml.

cd <project-root>
BACKEND_ENV_FILE=$HOME/.env/orchestra/.env.backend \
FRONTEND_ENV_FILE=$HOME/.env/orchestra/.env.frontend \
make dev.docker.up

Useful endpoints while debugging:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000/docs
• Dozzle log viewer: http://localhost:8088

Tail the main service logs in one stream:

make dev.docker.logs

If you also want the sandbox exec server inside the stack, start with COMPOSE_PROFILES=tools make dev.docker.up.

1. Setup Server Environment

   cd <project-root>/backend
   make dev
   

   Manual setup (if Makefile unavailable)

   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

• Configuring gcalcli
• Issues Logging into gcalcli

🗺️ Roadmap

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

March 2026

February 2026

January 2026

See Changelog.md for the full release history.

🏢 Enterprise

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

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"
SHELL_EXEC_SERVER_URL="http://exec_server:3005/exec"

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

🧱 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
cp docker/README.md backend/README.md
cd backend
docker build -t orchestra:local .

⚙️ Environment Variables

Application Config

Database

AI Providers (at least one required)

Tool Config

Distributed Workers (Optional)

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

Storage

🗄️ 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