🛰️ OpenCodeSpace

Launch disposable VS Code development environments for YOLO mode development with AI tools like Claude Code and Gemini. Either locally with Docker or remotely on Fly.io (AWS, GCE, Digital Ocean coming soon). Like Code Spaces, but fully self hosted.

🔄 Recently Updated: Added AI API keys configuration, auto-generated VS Code passwords, and enhanced interactive setup wizard.

---

✨ Features

• 🐳 Local Development: Run environments locally using Docker (Remote Docker coming soon)
• ☁️ Cloud Deployment: Deploy to Fly.io's global platform (AWS, GCE, Digital Ocean coming soon).
• 🤖 AI-Ready: Pre-configured with Claude Code and Gemini CLI, plus easy API key setup for Anthropic, Gemini, and OpenAI
• 💻 Editor Sync: Automatically detect and copy VS Code/Cursor settings & extensions
• 🔐 Secure: SSH key support for private Git repositories with auto-generated VS Code passwords
• ⚡ Fast Setup: One command deployment with smart defaults and guided setup wizard
• 🌟 Interactive & Automated: Full CLI with -y flag for CI/CD
• 📁 Flexible: Upload folders or work with empty environments
• 🔧 Cross-Platform: Works on macOS, Windows, and Linux (Untested on Linux and Windows)

---

🚀 Quick Start

📦 Installation

pip install opencodespace

🎯 Deploy Your First Environment

# Interactive setup with editor detection (recommended)
opencodespace

# Non-interactive with defaults (skips editor config)
opencodespace -y

# Deploy specific directory
opencodespace deploy /path/to/project

# Deploy with specific platform
opencodespace deploy --platform fly

🛑 Managing Environments

# Stop environment
opencodespace stop

# Remove environment completely  
opencodespace remove

# List available providers
opencodespace --list-providers

---

💻 CLI Reference

Commands

Command	Description
opencodespace	Deploy current directory with interactive setup
opencodespace deploy [path]	Deploy specific directory
opencodespace stop [path]	Stop the environment
opencodespace remove [path]	Remove the environment

Global Options

Option	Description
-y, --yes	Skip interactive prompts, use defaults (no editor config)
--list-providers	Show available deployment providers
-v, --version	Show version information

Examples

# Full interactive setup with editor detection
opencodespace

# Quick deployment with defaults (no editor sync)
opencodespace -y

# Deploy to specific platform
opencodespace deploy --platform local

# Deploy with editor configuration for specific directory
opencodespace deploy /path/to/my-project

---

⚙️ Configuration

Configuration is stored in .opencodespace/config.toml in your project directory.

Example Configuration

name = "my-project-local"
platform = "local"
upload_folder = true
git_branching = true
dockerfile = "Dockerfile"
vscode_password = "abc123XYZ!@#"
api_keys = []

[env]
GITHUB_TOKEN = "ghp_..."

[ai_api_keys]
ANTHROPIC_API_KEY = "sk-ant-..."
GEMINI_API_KEY = "AIza..."
OPENAI_API_KEY = "sk-..."

[vscode_config]
copy_settings = true
copy_extensions = true
detected_editors = ["vscode", "cursor"]
vscode_settings_path = "/Users/john/Library/Application Support/Code/User/settings.json"
cursor_settings_path = "/Users/john/Library/Application Support/Cursor/User/settings.json"
vscode_extensions_list = [
    "ms-python.python",
    "ms-vscode.vscode-typescript-next",
    "github.copilot"
]
cursor_extensions_list = [
    "cursor.ai",
    "ms-python.python",
    "ms-vscode.vscode-json"
]

Configuration Options

Option	Default	Description
name	Auto-generated	Environment name
platform	"local"	Deployment platform (local or fly)
upload_folder	true	Upload current directory to container
git_branching	true	Enable Git branch management
dockerfile	"Dockerfile"	Custom Dockerfile name
vscode_password	Auto-generated	VS Code/Coder access password
api_keys	[]	Legacy environment variables list (use ai_api_keys instead)
ai_api_keys.ANTHROPIC_API_KEY	""	Anthropic (Claude) API key
ai_api_keys.GEMINI_API_KEY	""	Google Gemini API key
ai_api_keys.OPENAI_API_KEY	""	OpenAI (ChatGPT) API key

Editor Configuration Options

Option	Default	Description
vscode_config.copy_settings	false	Copy editor settings to remote
vscode_config.copy_extensions	false	Install extensions in remote
vscode_config.detected_editors	[]	List of detected editors
vscode_config.*_settings_path	null	Path to local settings file
vscode_config.*_extensions_list	[]	List of extensions to install

---

🛠 Requirements

For Local Development

• Python 3.7+
• Docker - Install Docker Desktop

For Fly.io Deployment

• Python 3.7+
• flyctl - Install flyctl

For Editor Configuration Sync

• VS Code and/or Cursor installed locally (optional)
• Extensions accessible via code --list-extensions or cursor --list-extensions

---

🎯 Usage Scenarios

🏠 Local Development with Editor Sync

Perfect for testing with your complete development setup:

# Interactive setup with editor detection
opencodespace

# Manual configuration for local platform
opencodespace deploy --platform local

Your remote environment will have:

• ✅ All your installed extensions
• ✅ Your settings.json configuration
• ✅ Your themes and preferences
• ✅ Language-specific settings

☁️ Cloud Development with Full Setup

Deploy to Fly.io with your complete editor configuration:

# Interactive setup for cloud deployment
opencodespace

# Configure platform during setup
> Select platform: fly.io

# Access your fully configured environment
# at https://your-app.fly.dev

🤖 AI Development Environment

Pre-configured with AI tools, automatic password generation, and your editor setup:

# Full setup with AI tools and editor config
opencodespace

# During interactive setup, you'll configure:
# - Secure auto-generated VS Code password
# - VS Code/Cursor settings & extensions  
# - AI API keys (Anthropic, Gemini, OpenAI)
# - Git repository access
# - SSH keys for private repos

Your environment will include:

• ✅ Secure Access: Auto-generated password for VS Code/Coder
• ✅ AI Integration: API keys available as environment variables
• ✅ Complete Setup: Your editor preferences and extensions

🔒 Private Repositories with Editor Sync

Secure access to private repos with your development environment:

# Interactive setup handles everything
opencodespace

# Setup wizard will:
# 1. Detect your editors
# 2. Offer to copy settings/extensions
# 3. Configure SSH keys for Git access
# 4. Set up repository cloning

🚀 Team Development Environments

Share consistent development environments:

# Each team member gets the same setup
opencodespace

# Everyone can optionally overlay their own:
# - Editor preferences  
# - Extension sets
# - Personal settings

---

⚠️ Important Notes

Secure Access

• Auto-Generated Passwords: VS Code/Coder passwords are automatically generated during setup
• Password Storage: Passwords are saved in your .opencodespace/config.toml for reference
• Password Display: The password is displayed prominently during setup and after deployment

AI API Keys Configuration

• Structured Setup: AI API keys are now configured in the dedicated [ai_api_keys] section
• Environment Variables: Keys are automatically available as environment variables in your container
• Supported Services: Anthropic (Claude), Google Gemini, and OpenAI (ChatGPT)
• Optional Configuration: All AI API keys are optional and can be configured later

Editor Configuration

• Interactive Mode: Editor detection and configuration only happens during interactive setup
• Non-Interactive Mode: Use opencodespace -y to skip editor configuration for CI/CD
• Multiple Editors: If both VS Code and Cursor are detected, you can choose to copy from both
• Extension Compatibility: Cursor extensions are compatible with VS Code and will be installed

Empty Workspace Warning

When both SSH key and folder upload are disabled:

⚠️  Warning: No SSH key provided and folder upload disabled.
   The container will start with an empty workspace and no git access.
   Consider enabling folder upload or providing an SSH key for git operations.

Container Names

• Local: opencodespace-{name}
• Fly.io: Uses the app name directly

---

🔧 Development

Package Structure

opencodespace/
├── src/opencodespace/           # Modern src layout
│   ├── main.py                  # CLI with editor detection
│   ├── providers/               # Platform providers
│   └── .opencodespace/         # Docker templates with editor setup
├── setup.py                    # Package configuration
└── README.md                   # This file

Interactive Setup Flow

The interactive setup wizard follows an 8-step process:

1. Welcome & Version: Display welcome message and version information
2. Platform Selection: Choose between available providers (local, fly)
3. Git Repository Detection: Auto-detect and configure git repository cloning
4. SSH Key or Folder Upload: Setup SSH keys for private repos or folder upload
5. VS Code Password Generation: Automatically generate secure access password
6. Platform-specific Notes: Display platform-specific configuration details
7. Editor Configuration: Detect and copy VS Code/Cursor settings & extensions
8. AI API Keys Setup: Configure Anthropic, Gemini, and OpenAI API keys

Editor Detection Implementation

The editor detection system:

1. Detects Installations: Checks for code and cursor commands plus platform-specific paths
2. Reads Settings: Locates and reads settings.json files from user data directories
3. Lists Extensions: Uses --list-extensions to get installed extensions
4. Configures Remote: Passes configuration to containers via environment variables
5. Installs Everything: Uses code-server --install-extension to install extensions

AI API Keys Configuration

During interactive setup, you can configure AI API keys for popular services:

• Anthropic (Claude): For Claude AI development assistance
• Google Gemini: For Google's Gemini AI models
• OpenAI (ChatGPT): For OpenAI's GPT models

These keys are securely stored in your config and available as environment variables in your development environment, making it easy to use AI tools directly in your code.

🔨 Development & Building

This project includes a comprehensive build system with multiple interfaces for development tasks.

Quick Development Setup

git clone https://github.com/devadutta/opencodespace.git
cd opencodespace

# Install dependencies and package in development mode
make install
# or: python build.py install
# or: ./build.sh install

# Run quick tests during development
make test-quick
# or: python build.py test --quick
# or: ./build.sh test-quick

Build System Overview

Three equivalent interfaces for development tasks:

• python build.py [command] - Feature-rich Python script (cross-platform)
• make [target] - Traditional Makefile interface (Unix/Linux)
• ./build.sh [command] - Simple shell script wrapper

Available Commands

Command	Description
install	Install dependencies and package in development mode
test	Run the complete test suite
test-quick	Run quick tests (recommended for development)
clean	Clean build artifacts and cache files
build	Build package for distribution
lint	Run code quality checks
all	Run complete build pipeline

Examples

# Development workflow
make install          # Set up development environment
make test-quick      # Test your changes
make all            # Full build pipeline before PR

# Building for distribution
make clean
make build

# Get help
python dev-build.py help
make help
./build.sh help

For detailed documentation, see BUILD.md.

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• code-server - VS Code in the browser
• Fly.io - Global application platform
• Docker - Containerization platform
• VS Code - The editor that inspired this project
• Cursor - AI-powered code editor

---

Made with ❤️ for developers who want instant, disposable development environments with their perfect editor setup.