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.

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)

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

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

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, and the GUI for viewing the Postgres DB.

   cd <project-root>
   docker compose up postgres pgadmin

3. 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

4. Setup Client Environment

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

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

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

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

• Configuring gcalcli
• Issues Logging into gcalcli

• Human-In-The-Loop

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.

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

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

Pull the latest image from GitHub Container Registry:

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

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"

From the project root directory:

# Start database and backend
docker compose up postgres orchestra

# Or start all services
docker compose up

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

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

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

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

docker compose build orchestra

# Copy README first, then build
cp docker/README.md backend/README.md
cd backend
docker build -t orchestra:local .

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

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

• 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

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

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.

# Check logs
docker compose logs orchestra

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

# Ensure postgres is running
docker compose ps postgres

# Check postgres logs
docker compose logs postgres

# 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