🛰️ 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 and open source.

✨ 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

Note: Run the interactive setup wizard to generate .opencodespace/config.toml

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

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/ngramai/opencodespace.git
cd opencodespace

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

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

Build System Overview

Three equivalent interfaces for development tasks:

python dev-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-dev-build.py help
make help
./build.sh help

For detailed documentation, see BUILD.md.

🤝 Contributing

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

📄 License

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

❤️ from ngram

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github		.github
src/opencodespace		src/opencodespace
tests		tests
.gitignore		.gitignore
BUILD.md		BUILD.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
TESTING_SUMMARY.md		TESTING_SUMMARY.md
ci.yml		ci.yml
dev-build.py		dev-build.py
dev-build.sh		dev-build.sh
publish-to-pypi.yml		publish-to-pypi.yml
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
run_tests.py		run_tests.py
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

🛰️ OpenCodeSpace

✨ Features

🚀 Quick Start

📦 Installation

🎯 Deploy Your First Environment

🛑 Managing Environments

💻 CLI Reference

Commands

Global Options

Examples

⚙️ Configuration

Configuration Options

Editor Configuration Options

🛠 Requirements

For Local Development

For Fly.io Deployment

For Editor Configuration Sync

🎯 Usage Scenarios

🏠 Local Development with Editor Sync

☁️ Cloud Development with Full Setup

🤖 AI Development Environment

🔒 Private Repositories with Editor Sync

🚀 Team Development Environments

⚠️ Important Notes

Secure Access

AI API Keys Configuration

Editor Configuration

Empty Workspace Warning

Container Names

🔧 Development

Package Structure

AI API Keys Configuration

🔨 Development & Building

Quick Development Setup

Build System Overview

Available Commands

Examples

🤝 Contributing

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages