Claudex

Self-hosted Claude Code workspace with multi-provider routing, sandboxed execution, and a full web IDE.

Note: Claudex is under active development. Expect breaking changes between releases.

Community

Join the Discord server.

Why Claudex

• Claude Code as the execution harness, exposed through a self-hosted web UI
• One workflow across Anthropic, OpenAI, GitHub Copilot, OpenRouter, and custom Anthropic-compatible endpoints
• Anthropic Bridge routing for non-Anthropic providers while preserving Claude Code behavior
• Isolated sandbox backends (Docker, host)
• Extension surface: MCP servers, skills, agents, slash commands, prompts, and marketplace plugins
• Provider switching with shared working context

Core Architecture

React/Vite Frontend
  -> FastAPI Backend
  -> PostgreSQL + Redis (web/docker mode)
  -> SQLite + in-memory cache/pubsub (desktop mode)
  -> Sandbox runtime (Docker/Host)
  -> Claude Code CLI + claude-agent-sdk

Claude Code harness

Claudex runs chats through claude-agent-sdk, which drives the Claude Code CLI in the selected sandbox. This keeps Claude Code-native behavior for tools, session flow, permission modes, and MCP orchestration.

Anthropic Bridge for non-Anthropic providers

For OpenAI, OpenRouter, and Copilot providers, Claudex starts anthropic-bridge inside the sandbox and routes Claude Code requests through:

• ANTHROPIC_BASE_URL=http://127.0.0.1:3456
• provider-specific auth secrets such as OPENROUTER_API_KEY and GITHUB_COPILOT_TOKEN
• provider-scoped model IDs like openai/gpt-5.2-codex, openrouter/moonshotai/kimi-k2.5, copilot/gpt-5.2-codex

Claudex UI
  -> Claude Agent SDK + Claude Code CLI
  -> Anthropic-compatible request shape
  -> Anthropic Bridge (OpenAI/OpenRouter/Copilot)
  -> Target provider model

For Anthropic providers, Claudex uses your Claude auth token directly. For custom providers, Claudex calls your configured Anthropic-compatible base_url.

Key Features

• Claude Code-native chat execution through claude-agent-sdk
• Anthropic Bridge provider routing with provider-scoped models (openai/*, openrouter/*, copilot/*)
• Workspace-based project organization with per-workspace sandboxes
• Multi-sandbox runtime (Docker/Host)
• MCP + custom skills/agents/commands + plugin marketplace
• Streaming architecture with resumable SSE events and explicit cancellation
• Built-in recurring task scheduler (in-process async, no worker service)

Workspaces

Workspaces are the top-level organizational unit. Each workspace owns a dedicated sandbox and groups all related chats under one project context.

Source types

• Empty — creates a new empty directory in the sandbox
• Git clone — clones a repository (HTTPS or SSH) into a fresh sandbox
• Local folder — mounts an existing directory from the host filesystem (host sandbox only)

Sandbox isolation

Each workspace gets its own sandbox instance (Docker container or host process). Chats within a workspace share the same filesystem, installed tools, and .claude configuration. Switching between workspaces switches the entire execution environment.

Per-workspace sandbox provider

When creating a workspace you can override the default sandbox provider (Docker or Host). The provider is locked at creation time — all chats in that workspace use the same provider.

Workspace lifecycle

• Creating a workspace provisions the sandbox and initializes it with your settings (GitHub token, env vars, skills, agents, slash commands)
• Deleting a workspace soft-deletes all its chats and destroys the sandbox container

Quick Start (Web)

Requirements

• Docker + Docker Compose

Start

git clone https://github.com/Mng-dev-ai/claudex.git
cd claudex
docker compose -p claudex-web -f docker-compose.yml up -d

Open http://localhost:3000.

Stop and logs

docker compose -p claudex-web -f docker-compose.yml down
docker compose -p claudex-web -f docker-compose.yml logs -f

Desktop (macOS)

Desktop mode uses Tauri with a bundled Python backend sidecar on localhost:8081, with local SQLite storage.

Download prebuilt app

• Apple Silicon DMG: Latest Release

How it works

When running in desktop mode:

• Tauri hosts the frontend in a native macOS window
• the sidecar backend process serves the API on 8081
• desktop uses local SQLite plus in-memory cache/pubsub (no Postgres/Redis dependency required for desktop mode)

Tauri Desktop App
  -> React frontend (.env.desktop)
  -> bundled backend sidecar (localhost:8081)
  -> local SQLite database

Build and run from source

Requirements:

• Node.js
• Rust

Dev workflow:

cd frontend
npm install
npm run desktop:dev

Build (unsigned dev):

cd frontend
npm run desktop:build

App bundle output:

• frontend/src-tauri/target/release/bundle/macos/Claudex.app

Desktop troubleshooting:

• Backend unavailable: wait for sidecar startup to finish
• Database errors: verify local app data directory permissions
• Port conflict: free port 8081 if already in use

Provider Setup

Configure providers in Settings -> Providers.

• anthropic: paste token from claude setup-token
• openai: authenticate with OpenAI device flow in UI
• copilot: authenticate with GitHub device flow in UI
• openrouter: add OpenRouter API key and model IDs
• custom: set Anthropic-compatible base_url, token, and model IDs

Model examples

• OpenAI/Codex: gpt-5.2-codex, gpt-5.2, gpt-5.3-codex
• OpenRouter catalog examples: moonshotai/kimi-k2.5, minimax/minimax-m2.1, google/gemini-3-pro-preview
• Custom gateways: models like GLM-5, M2.5, or private org-specific endpoints (depends on your backend compatibility)

Shared Working Context

Switching providers within a workspace does not require a new workflow:

• Same sandbox filesystem/workdir
• Same .claude resources (skills, agents, commands)
• Same MCP configuration in Claudex
• Same workspace and chat history

This is the main value of using Claude Code as the harness while changing inference providers behind Anthropic Bridge.

Services and Ports (Web)

• Frontend: 3000
• Backend API: 8080
• PostgreSQL: 5432
• Redis: 6379
• VNC: 5900
• VNC Web: 6080
• OpenVSCode server: 8765

API and Admin

• API docs: http://localhost:8080/api/v1/docs
• Admin panel: http://localhost:8080/admin

Health and Ops

• Liveness endpoint: GET /health
• Readiness endpoint: GET /api/v1/readyz
  • web mode checks database + Redis
  • desktop mode checks database (SQLite) only

Deployment

• VPS/Coolify guide: docs/coolify-installation-guide.md
• Production setup uses frontend at / and API under /api/*

Screenshots

Tech Stack

• Frontend: React 19, TypeScript, Vite, TailwindCSS, Zustand, React Query
• Backend: FastAPI, SQLAlchemy, Redis, PostgreSQL/SQLite
• Runtime: Claude Code CLI, claude-agent-sdk, anthropic-bridge, uvicorn

License

Apache 2.0. See LICENSE.

Contributing

Contributions are welcome. Please open an issue first to discuss what you would like to change, then submit a pull request.

References

• Anthropic Claude Code SDK: docs.anthropic.com/s/claude-code-sdk
• Anthropic Bridge package: pypi.org/project/anthropic-bridge
• OpenAI Codex CLI sign-in: help.openai.com/en/articles/11381614
• OpenRouter API keys: openrouter.ai/docs/api-keys
• GitHub Copilot plans: github.com/features/copilot/plans