tylercollison2089/vscode-claude repository overview

⁠ClaudeConX

A Docker image providing a complete web-based development environment for Claude Code, built on top of the excellent linuxserver/code-server⁠ image.

⁠Overview

This Docker image bundles a web-based IDE (VS Code Server), Claude Code, a LiteLLM-powered model router, and Claude Threads into a comprehensive development environment accessible from any web browser and Mattermost client. Perfect for developers who want a self-contained, and highly flexible Claude Code workspace.

⁠What's Included

⁠Core Components

• VS Code Server - Full-featured VS Code running in your browser

  • Based on linuxserver/code-server⁠
  • Complete VS Code experience with extensions, terminal, and debugging
  • Responsive design supporting mobile, tablet, and desktop screens

• Claude Code - Anthropic's agentic coding tool

  • Claude Code Documentation⁠
  • AI-powered code generation, debugging, and automation
  • Direct terminal integration for seamless development workflows

• LiteLLM Router - Advanced model routing and provider proxy

  • LiteLLM Documentation⁠
  • Multi-provider support (Google AI Studio, NVIDIA NIM, Mistral, OpenCode Zen, Cerebras, EXA AI)
  • Content-aware routing (images → vision model, web search → search-capable model, complexity-based tiering)
  • Automatically routes requests to a curated collection of the most capable free models available based on API keys set (see "LiteLLM Router Configuration")
  • Fallback chains to overcome server side errors, availability, and rate limits

• Claude Threads - Real-time chat integration for Mattermost

  • GitHub Repository⁠
  • WebSocket-based bidirectional communication
  • Multi-platform support (Mattermost)

⁠Development Tools

• cconx - ClaudeConX Docker Management Tool

  • Command-line interface for managing ClaudeConX instances
  • Instance lifecycle management (start, stop, delete, status)
  • DNS and network configuration
  • Environment variable management with append/override logic

• build-env - Persistent Build Environment Manager

  • Creates and manages persistent Docker containers for build commands
  • Bidirectional file synchronization between host and container
  • Environment isolation with dedicated containers per workspace
  • Smart conflict resolution using modification timestamps

⁠Development Stack

• Node.js 22 - Latest LTS version with npm package manager
• Full Linux development environment - Based on Ubuntu with common development tools
• Web-based terminal - Integrated terminal access within VS Code
• Docker-in-Docker support - Run Docker commands from within the container

⁠Quick Start

# Run the container
docker run -d \
  --name=claude-dev \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e SUDO_PASSWORD=password \
  -e DEFAULT_WORKSPACE=/workspace \
  -e PWA_APPNAME=code-server \
  -e NIM_API_KEY=your-nvidia-nim-api-key \
  -e GOOGLE_API_KEY=your-google-ai-studio-api-key \
  -e MISTRAL_API_KEY=your-mistral-api-key \
  -e CEREBRAS_API_KEY=your-cerebras-api-key \
  -e OPENCODE_ZEN_API_KEY=your-opencode-zen-api-key \
  -e EXA_API_KEY=your-exa-api-key \
  -p 8443:8443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /path/to/your/code:/workspace \
  --restart unless-stopped \
  tylercollison2089/claude-conx

# Access at http://localhost:8443

⁠Environment Variables Reference

This container supports extensive configuration through environment variables.

⁠Container Configuration

⁠Authentication & Access Control

⁠Claude Code Configuration

⁠LiteLLM Router Configuration

Claude Code is pre-configured to route all requests through the LiteLLM proxy at http://127.0.0.1:5090. The router automatically selects models based on request content:

⁠Claude Threads Configuration

⁠build-env Configuration

⁠Git Repository Setup

⁠Knowledge Repository Integration

⁠Docker Compose

services:
  claude-dev:
    image: tylercollison2089/claude-conx:latest
    container_name: claude-dev
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - PASSWORD=password # Optional
      - HASHED_PASSWORD= # Optional
      - SUDO_PASSWORD=password # Optional
      - SUDO_PASSWORD_HASH= # Optional
      - PROXY_DOMAIN=code-server.my.domain # Optional
      - DEFAULT_WORKSPACE=/workspace
      - PWA_APPNAME=code-server # Optional
      - CLAUDE_CODE_PERMISSION_MODE=acceptEdits
      - NIM_API_KEY=your-nvidia-nim-api-key # Required to use NIM models
      - GOOGLE_API_KEY=your-google-ai-studio-api-key # Required to use Google models
      - MISTRAL_API_KEY=your-mistral-api-key # Required to use Mistral models
      - CEREBRAS_API_KEY=your-cerebras-api-key # Required to use Cerebras models
      - OPENCODE_ZEN_API_KEY=your-opencode-zen-api-key # Required to use OpenCode Zen models
      - EXA_API_KEY=your-exa-api-key # Required for EXA AI websearch
      # Claude Code Plugins (optional)
      - CLAUDE_MARKETPLACES=anthropics/claude-plugins-official
      - CLAUDE_PLUGINS=ralph-loop,superpowers
      # Git repository setup (optional)
      - GIT_REPO_URL=https://github.com/user/repo.git
      - GIT_BRANCH_NAME=feature-branch
      # Knowledge repositories (optional)
      - KNOWLEDGE_REPOS=https://github.com/user/docs.git:main:README.md,docs/guide.md
      # Claude Threads (optional)
      - ENABLE_THREADS=true
      - IDE_ADDRESS=http://localhost:8443
      - MM_ADDRESS=http://mattermost.example.com:8065
      - MM_CHANNEL=claude-code
      - MM_TOKEN=your-bot-token
      - MM_TEAM=engineering
      - MM_BOT_NAME=claude-code
      - THREADS_CHROME=true
      - THREADS_WORKTREE_MODE=off
      - THREADS_SKIP_PERMISSIONS=true
    ports:
      - "8443:8443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # Optional for docker support
      - /path/to/code-server/config:/config # Only specify if using existing configuration
      - /path/to/your/code:/workspace # Only specify if GIT_REPO_URL is unset
    restart: unless-stopped

⁠Configuration

⁠Claude Code Setup

Claude Code is pre-configured to route all requests through the LiteLLM proxy at http://127.0.0.1:5090. No additional setup is needed — just open the terminal in VS Code and run claude.

To override the default routing and use a specific model directly, set the model environment variable to the desired LiteLLM model or model group:

environment:
  - ANTHROPIC_DEFAULT_SONNET_MODEL=lite-llm/think # Use complex-reasoning tier
  - ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-ai/deepseek-v4-flash # Use a fast model

⁠LiteLLM Router

The LiteLLM proxy provides a three-stage routing pipeline:

1. Image detection — requests with image data automatically route to lite-llm/image (Google Gemini 3.5 Flash)
2. Web search detection — requests with web search tools route to lite-llm/webSearch (Google Gemini 3.5 Flash)
3. Complexity routing — all other requests are scored by complexity and routed to either lite-llm/default (OpenCode Zen DeepSeek v4 Flash) for simple tasks or lite-llm/think (NVIDIA NIM DeepSeek v4 Pro) for complex reasoning

The routing configuration lives in /lite-llm/lite-llm-default.yaml. Key model groups:

Each model group has a fallback chain defined in the YAML config, so if the primary model is unavailable, traffic routes to alternative providers automatically.

⁠Claude Threads

Enable real-time Mattermost integration:

environment:
  - ENABLE_THREADS=true
  - MM_ADDRESS=http://mattermost.example.com:8065
  - MM_TOKEN=your-bot-token
  - MM_CHANNEL=claude-code
  - MM_TEAM=engineering
  - MM_BOT_NAME=claude-code

Features:

• WebSocket-based real-time communication
• Automatic channel creation if not exists
• User session management
• Support for worktree isolation mode

⁠cconx Usage

cconx provides command-line management of ClaudeConX instances:

# Start a new instance
cconx start my-instance

# Start with port and environment variable overrides
cconx start dev-instance --port 8080 --env CLAUDE_CODE_PERMISSION_MODE=bypassPermissions

# Show instance status
cconx status

# Stop an instance
cconx stop my-instance

# Delete an instance (container and config)
cconx delete my-instance

⁠build-env Usage

build-env creates persistent Docker containers for build commands:

# Set required environment variables
export BUILD_CONTAINER="python:3.12-slim"
export DEFAULT_WORKSPACE="/path/to/workspace"

# Run commands in the build environment
build-env python --version
build-env npm install
build-env npm run build

# Shutdown the build environment container
build-env --exit

⁠Git Repository Auto-Setup

Automatically clone and configure a repository on startup:

environment:
  - GIT_REPO_URL=https://github.com/user/repo.git
  - GIT_BRANCH_NAME=feature/my-branch # Optional: auto-generated if not set

The container will:

1. Clone the repository to /workspace
2. Create/checkout the specified branch
3. Set appropriate permissions

⁠Knowledge Repository Integration

Combine markdown documentation from multiple repositories:

environment:
  - KNOWLEDGE_REPOS=https://github.com/user/repo1.git:main:README.md,docs/guide.md;https://github.com/user/repo2.git:develop:docs/api.md

The combined documentation is saved as /workspace/CLAUDE.md.

Format:

• ; separates repositories
• : separates URL, optional branch, and file list
• , separates files within a repository

⁠Permission Control

Configure Claude Code security settings:

⁠Docker-in-Docker Support

Run Docker commands inside the container:

# List containers on the host
docker ps

# Build containers
docker build -t my-app .

Security Note: Mounting /var/run/docker.sock gives the container full control over the host's Docker daemon.

⁠Features

⁠VS Code Integration

• Full VS Code feature set including extensions
• Integrated terminal and debugging
• Git version control support
• Multi-language support

⁠AI-Powered Development

• Code generation from natural language
• Automated debugging and issue resolution
• Codebase navigation and understanding
• Automated testing and documentation

⁠Model Flexibility

• Multiple AI provider support via LiteLLM
• Content-aware routing (images, web search, complexity-based tiering)
• Automatic fallback chains for high availability

⁠Auto-Configuration

• Git repository cloning and branch setup
• Knowledge repository markdown combination
• LiteLLM routing configuration loaded on startup
• Claude Code plugin and marketplace setup
• Mattermost channel auto-creation

⁠Building Locally

git clone https://github.com/TylerCollison/vscode-claude.git
cd claude-conx
docker build -t tylercollison2089/vscode-claude:latest .

⁠Troubleshooting

⁠Container-Level Debugging

# Check container logs
docker logs claude-dev

# Inspect container environment
docker exec claude-dev env

# Test internal services
docker exec claude-dev curl -I http://localhost:8443

⁠Application-Level Debugging

# VS Code Server status
docker exec claude-dev ps aux | grep code-server

# Claude Code functionality
docker exec claude-dev claude --version

# Check LiteLLM proxy status
docker exec claude-dev curl -s http://127.0.0.1:5090/health

⁠Common Issues

Claude Code Authentication:

• Verify Claude Code installation: which claude
• Check network connectivity: curl -I https://api.claude.com

VS Code Connection:

• Verify port mapping: docker port claude-dev
• Check for port conflicts: netstat -tulpn | grep 8443

Mattermost Integration:

• Test API connectivity: curl -H "Authorization: Bearer $MM_TOKEN" "$MM_ADDRESS/api/v4/channels"
• Verify bot permissions for channel access
• Check WebSocket connectivity if using Claude Threads

LiteLLM Configuration:

• Verify LiteLLM is running: curl -s http://127.0.0.1:5090/health

cconx Issues:

• Verify cconx installation: which cconx
• Check instance configuration: ls ~/.cconx/instances/
• Validate Docker network: docker network ls

build-env Issues:

• Verify Docker daemon is running: docker ps
• Check workspace permissions: ls -la $DEFAULT_WORKSPACE
• Validate container image: docker pull $BUILD_CONTAINER

⁠Credits

• linuxserver/code-server⁠ — Base VS Code Server environment
• Anthropic Claude Code⁠ — AI coding assistant
• LiteLLM⁠ — Model routing and provider proxy
• Claude Threads⁠ — Real-time chat integration

⁠Support

⁠Documentation

• VS Code: vscode server documentation⁠
• Claude Code: Claude Code documentation⁠
• linuxserver/code-server: linuxserver/code-server documentation⁠
• LiteLLM: LiteLLM Documentation⁠
• Claude Threads: Claude Threads GitHub⁠
• cconx: cconx GitHub⁠
• build-env: build-env GitHub⁠
• tylercollison2089/vscode-claude: ClaudeConX GitHub⁠

⁠Issues

• VS Code: vscode GitHub issue tracker⁠
• linuxserver/code-server: linuxserver/code-server GitHub issue tracker⁠
• Claude Code: Claude Code GitHub issue tracker⁠
• LiteLLM: LiteLLM GitHub issue tracker⁠
• Claude Threads: Claude Threads GitHub issue tracker⁠
• cconx: cconx GitHub issue tracker⁠
• build-env: build-env GitHub issue tracker⁠
• tylercollison2089/vscode-claude: ClaudeConX GitHub issue tracker⁠

⁠License

This Docker image is provided as-is. Please refer to the individual component licenses for linuxserver/code-server, Claude Code, LiteLLM, and Claude Threads.