Open Commander


     ██████╗ ██████╗ ███████╗███╗   ██╗
    ██╔═══██╗██╔══██╗██╔════╝████╗  ██║
    ██║   ██║██████╔╝█████╗  ██╔██╗ ██║
    ██║   ██║██╔═══╝ ██╔══╝  ██║╚██╗██║
    ╚██████╔╝██║     ███████╗██║ ╚████║
     ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═══╝

     ██████╗ ██████╗ ███╗   ███╗███╗   ███╗ █████╗ ███╗   ██╗██████╗ ███████╗██████╗
    ██╔════╝██╔═══██╗████╗ ████║████╗ ████║██╔══██╗████╗  ██║██╔══██╗██╔════╝██╔══██╗
    ██║     ██║   ██║██╔████╔██║██╔████╔██║███████║██╔██╗ ██║██║  ██║█████╗  ██████╔╝
    ██║     ██║   ██║██║╚██╔╝██║██║╚██╔╝██║██╔══██║██║╚██╗██║██║  ██║██╔══╝  ██╔══██╗
    ╚██████╗╚██████╔╝██║ ╚═╝ ██║██║ ╚═╝ ██║██║  ██║██║ ╚████║██████╔╝███████╗██║  ██║
     ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚═╝     ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═════╝ ╚══════╝╚═╝  ╚═╝

        ┌─────────────────────────────────────────────────────────────┐
        │  🤖 Delegate tasks to AI agents in isolated containers 🐳  │
        └─────────────────────────────────────────────────────────────┘

Open Commander

Delegate tasks to AI coding agents with full isolation and control.

Open Commander is a self-hosted platform that lets you delegate coding tasks to AI agents (Claude, OpenAI Codex, Cursor, and more) running in isolated Docker containers. Each agent gets its own secure environment with controlled internet access, making it safe to let AI work on your codebase autonomously.

Why Open Commander?

Secure by Design

Isolated Execution: Each agent runs in its own Docker container with no direct access to your host system
Controlled Egress: Outbound internet access goes through a proxy with configurable allowlists
No Credential Leaks: API keys and tokens stay on the server, never exposed to agents

Autonomous Task Execution

Fire and Forget: Submit a task via API and let the agent work independently
Automatic Repository Cloning: Just provide owner/repo — the system clones it automatically
Progress Tracking: Monitor task status, view logs, and get results via API or web UI

Multi-Agent Support

Choose Your Agent: Claude, OpenAI Codex, Cursor, or custom agents
Consistent Interface: Same API for all agents
Agent-Specific Configurations: Customize settings per agent type

Developer-Friendly API

REST API: Create tasks, check status, and retrieve results programmatically
GitHub Integration: Verify repository access before delegating tasks
Webhooks Ready: Integrate with CI/CD pipelines and automation tools

Self-Hosted & Private

Your Infrastructure: Run on your own servers or cloud
Your Data: Code never leaves your environment
Your Rules: Full control over access, quotas, and permissions

Quick Start

Prerequisites

Docker and Docker Compose
Bun (for local development)
A GitHub Personal Access Token (for cloning private repositories)

1. Clone the Repository

git clone https://github.com/your-org/open-commander.git
cd open-commander

2. Start Infrastructure Services

Start the required services (PostgreSQL, Redis, Docker-in-Docker, Egress Proxy):

docker compose up -d

This starts:

PostgreSQL (port 5432) — Database for tasks, users, and settings
Redis (port 6379) — Job queue for task execution
Docker-in-Docker — Isolated Docker daemon for running agent containers
Egress Proxy (port 3128) — Controlled outbound internet access
Worker Jobs — Background worker for processing task executions
Worker Board (port 4000) — Bull Board UI for monitoring job queues

3. Configure Environment

# Copy the example environment file
cp apps/web/.env.example apps/web/.env

Edit apps/web/.env and configure the required variables:

# Required: Path to your Open Commander installation
COMMANDER_BASE_PATH=/path/to/open-commander

# Required: Directory where repositories will be cloned
# Agent containers will have access to this directory
AGENT_WORKSPACE=/path/to/your/projects

# Required: Your GitHub token for cloning repositories
# Create at: https://github.com/settings/tokens
# Recommended scopes: repo (for private repos)
GITHUB_TOKEN=ghp_your_token_here

# Database (matches docker-compose defaults)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/commander_dev

# App URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Disable auth for local development (never in production!)
NEXT_PUBLIC_DISABLE_AUTH=true

4. Install Dependencies & Setup Database

# Install dependencies
bun install

# Generate Prisma client and run migrations
cd apps/web
bunx prisma generate
bunx prisma migrate deploy

5. Start the Application

# From the apps/web directory
bun run dev

The application will be available at http://localhost:3000.

Environment Configuration

Required Variables

Variable	Description
`COMMANDER_BASE_PATH`	Absolute path to the Open Commander installation
`AGENT_WORKSPACE`	Directory where repositories are cloned and mounted into containers
`DATABASE_URL`	PostgreSQL connection string
`GITHUB_TOKEN`	GitHub PAT for cloning repositories and API access

Authentication (Optional)

For production, configure at least one OAuth provider:

# GitHub OAuth
NEXT_PUBLIC_GITHUB_AUTH_ENABLED=true
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

# Google OAuth
NEXT_PUBLIC_GOOGLE_AUTH_ENABLED=true
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret

Docker Configuration (Advanced)

These have sensible defaults but can be customized:

# Agent container image
TTYD_IMAGE=opencommander/agent:latest

# Docker networks (must match docker-compose.yml)
TTYD_INTERNAL_NETWORK=open-commander_open-commander-internal
TTYD_INGRESS_NETWORK=open-commander_open-commander-ingress

# Egress proxy settings
TTYD_EGRESS_PROXY_HOST=egress-proxy
TTYD_EGRESS_PROXY_PORT=3128

See apps/web/.env.example for the complete list of configuration options.

Usage

Creating an API Key

Open the web UI at http://localhost:3000
Go to Settings → API Clients
Create a new API client and generate a secret key
Save the key securely — it's only shown once!

Monitoring Job Queues

The Bull Board UI is available at http://localhost:4000/admin/queues for monitoring and managing background jobs.

Delegating a Task via API

curl -X POST http://localhost:3000/api/tasks \
  -H "Authorization: Bearer oc_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Fix the bug in src/utils/auth.ts where tokens expire too early",
    "agentId": "claude",
    "repository": "your-org/your-repo"
  }'

The repository is automatically cloned — the agent starts with it as the working directory. No need to include clone instructions in the task.

Checking Task Status

# Get task by ID
curl http://localhost:3000/api/tasks/clx789abc123 \
  -H "Authorization: Bearer oc_sk_your_api_key"

# List all tasks
curl http://localhost:3000/api/tasks \
  -H "Authorization: Bearer oc_sk_your_api_key"

Verifying Repository Access

Before delegating a task, you can verify the server has access to the repository:

curl -X POST http://localhost:3000/api/github/verify-access \
  -H "Content-Type: application/json" \
  -d '{"repository": "your-org/your-repo"}'

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Open Commander                            │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   Web UI    │  │  REST API   │  │  Job Queue  │              │
│  │  (Next.js)  │  │   (tRPC)    │  │  (BullMQ)   │              │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
│         │                │                │                      │
│         └────────────────┼────────────────┘                      │
│                          │                                       │
│                    ┌─────▼─────┐                                 │
│                    │ PostgreSQL │                                │
│                    └───────────┘                                 │
├─────────────────────────────────────────────────────────────────┤
│                     Docker-in-Docker                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   Agent 1   │  │   Agent 2   │  │   Agent N   │              │
│  │  (Claude)   │  │   (Codex)   │  │    (...)    │              │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
│         │                │                │                      │
│         └────────────────┼────────────────┘                      │
│                          │                                       │
│                    ┌─────▼─────┐                                 │
│                    │Egress Proxy│───────► Internet (filtered)    │
│                    └───────────┘                                 │
└─────────────────────────────────────────────────────────────────┘

API Documentation

Full API documentation is available at apps/web/public/skill.md or via the web UI.

Endpoints

Method	Endpoint	Description
`GET`	`/api/tasks`	List tasks
`POST`	`/api/tasks`	Create a new task
`GET`	`/api/tasks/:id`	Get task details
`POST`	`/api/github/verify-access`	Verify repository access

Development

Project Structure

open-commander/
├── apps/
│   └── web/                 # Next.js application
│       ├── src/
│       │   ├── app/         # Next.js app router
│       │   ├── components/  # React components
│       │   ├── lib/         # Core services (docker, git)
│       │   └── server/      # tRPC routers & job workers
│       └── prisma/          # Database schema
├── docker/
│   ├── agent/               # Agent container Dockerfile
│   └── egress/              # Egress proxy configuration
└── docker-compose.yml       # Infrastructure services

Running Tests

bun test

Building for Production

cd apps/web
bun run build

Building Docker images locally

All images use the repo root as the Docker build context.

Commander (web app)

docker build \
  -f docker/commander/Dockerfile \
  --target runner \
  -t ghcr.io/open-commander/open-commander-web:local \
  .

Egress proxy

docker build \
  -f docker/egress/Dockerfile \
  -t ghcr.io/open-commander/open-commander-egress:local \
  docker/egress

Agent core image

docker build \
  -f docker/core/Dockerfile \
  -t ghcr.io/open-commander/open-commander-core:local \
  docker/core

Agent image (requires core to be built first)

docker build \
  -f docker/agent/Dockerfile \
  -t ghcr.io/open-commander/open-commander-agent:local \
  docker/agent

Multi-platform builds (amd64 + arm64)

docker buildx create --use --name multi-platform

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -f docker/commander/Dockerfile \
  --target runner \
  -t ghcr.io/open-commander/open-commander-web:local \
  --load \
  .

Testing the deploy stack with local images

Build the deploy images, tag them to match what the compose file expects, then run:

docker build -f docker/commander/Dockerfile --target runner -t ghcr.io/open-commander/open-commander-web:latest .
docker build -f docker/egress/Dockerfile -t ghcr.io/open-commander/open-commander-egress:latest docker/egress

cp .env.deploy.example .env.deploy  # fill in values
docker compose -f docker-compose.deploy.yml -f docker-compose.dbs.yml --env-file .env.deploy up -d

Security Considerations

Never expose the API without authentication in production
Review egress allowlists in docker/egress/allowed-domains.txt
Rotate GitHub tokens regularly
Use environment-specific secrets — don't commit .env files
Monitor agent activities through logs and the web UI

License

MIT License — see LICENSE for details.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Name		Name	Last commit message	Last commit date
.cursor		.cursor
.github/workflows		.github/workflows
.state		.state
.windsurf		.windsurf
agents		agents
apps/web		apps/web
docker		docker
docs		docs
packages		packages
.dockerignore		.dockerignore
.env.deploy.example		.env.deploy.example
.gitignore		.gitignore
.nvmrc		.nvmrc
AGENT.md		AGENT.md
CLAUDE.md		CLAUDE.md
README.md		README.md
biome.json		biome.json
build-images.sh		build-images.sh
bun.lock		bun.lock
docker-compose.core.yml		docker-compose.core.yml
docker-compose.dbs.yml		docker-compose.dbs.yml
docker-compose.deploy.yml		docker-compose.deploy.yml
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
nixpacks.toml		nixpacks.toml
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Open Commander

Why Open Commander?

Secure by Design

Autonomous Task Execution

Multi-Agent Support

Developer-Friendly API

Self-Hosted & Private

Quick Start

Prerequisites

1. Clone the Repository

2. Start Infrastructure Services

3. Configure Environment

4. Install Dependencies & Setup Database

5. Start the Application

Environment Configuration

Required Variables

Authentication (Optional)

Docker Configuration (Advanced)

Usage

Creating an API Key

Monitoring Job Queues

Delegating a Task via API

Checking Task Status

Verifying Repository Access

Architecture

API Documentation

Endpoints

Development

Project Structure

Running Tests

Building for Production

Building Docker images locally

Security Considerations

License

Contributing

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages