Claudex

What is Claudex about?

Claudex delivers a self‑hosted Claude Code environment where developers can write, run, and debug code through a browser‑based IDE. It unifies multiple LLM providers (Anthropic, OpenAI, OpenRouter, GitHub Copilot, or custom Anthropic‑compatible endpoints) behind an Anthropic‑compatible bridge while preserving Claude Code‑native tooling, permissions, and MCP orchestration.

How to use Claudex?

• Web mode (Docker Compose)

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

  Access the UI at http://localhost:3000. Backend API runs on 8080 with PostgreSQL and Redis containers.

• Desktop mode (macOS, Tauri)

  1. Download the latest DMG from the GitHub releases page.
  2. Launch the app; it starts a local side‑car backend on localhost:8081 and uses SQLite for storage.
  3. For development, run:

     cd frontend
     npm install
     npm run desktop:dev
     

• Workspace management

  • Create a workspace → choose source type (empty, Git clone, local folder) → select sandbox provider (Docker or Host).
  • Workspaces isolate filesystems, installed tools, and .claude configuration; chats share the same sandbox.
  • Delete a workspace to destroy its sandbox and soft‑delete chats.

Key Features

• Claude Code‑native chat execution via claude-agent-sdk.
• Anthropic Bridge that routes OpenAI, OpenRouter, and Copilot requests while keeping Claude‑compatible request shape.
• Per‑workspace sandbox isolation (Docker container or host process).
• Multi‑provider support with shared working context; switch providers without losing filesystem or chat history.
• Built‑in MCP extensibility: custom skills, agents, slash commands, and marketplace plugins.
• Streaming SSE architecture with resumable events and explicit cancellation.
• Recurring task scheduler running inside the FastAPI process (no external worker needed).
• Flexible storage: PostgreSQL + Redis for web mode, SQLite + in‑memory cache for desktop mode.
• VNC and OpenVSCode server ports exposed for remote visual debugging.

Use Cases

• AI‑assisted coding across different model providers while keeping a single project workspace.
• Sandboxed execution of generated code in isolated Docker containers to ensure security.
• Rapid prototyping of agents and skills using the MCP extension surface.
• Multi‑model evaluation where developers compare outputs from Claude, OpenAI, and other models side‑by‑side.
• Education & workshops that need a ready‑to‑use web IDE with AI assistance and no external cloud dependencies.

FAQ

Q: How do I switch the LLM provider for an existing workspace? A: Open Settings → Providers, select the desired provider, and the workspace will continue using the same sandbox and chat history.

Q: Can I run Claudex without Docker? A: Yes. Desktop mode runs a bundled Python side‑car and uses a host‑based sandbox; no Docker is required.

Q: What runtimes are supported inside the sandbox? A: Any tool installable in the container/host environment (Node, Python, Rust, etc.) can be used through Claude Code’s tool execution flow.

Q: How are custom MCP servers added? A: Via the Extensions UI – upload a Docker image or point to a running service that implements the MCP protocol; Claudex will register it as a skill/agent.

Q: Is data persisted between restarts? A: In web mode, PostgreSQL stores workspace metadata and chat history; Redis caches live state. Desktop mode persists everything in a local SQLite file.

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