Skip to content

charcoal-cli

The charcoal-cli is a lightweight orchestrator for local and remote development environments. Built with Dev Container, it bridges the gap between local Docker-based workflows and cloud-scale development environments.

Charcoal gives you consistency with the flexibility of local execution or self-hosted infrastructure. It provisions, manages, and connects to development environments (IDEs or shells) with minimal overhead.

Quick Example

# Clone a repo and open it in a browser-based VS Code
charcoal up --ide https://github.com/octocat/hello-world.git

# See all your running workspaces
charcoal list

# Stop a workspace
charcoal stop hello-world

How It Works

Charcoal wraps the Dev Container CLI and Docker to create reproducible development environments. When you run charcoal up, it:

  1. Clones the repository into ~/.local-codespaces/
  2. Detects or generates a devcontainer.json
  3. Builds and starts the container with devcontainer up
  4. Launches either an interactive shell or a web-based VS Code (OpenVSCode Server)

Features

  • Dev Container Native — Full devcontainer.json support for reproducible environments
  • Web IDE Integration — One-command browser-based VS Code via OpenVSCode Server
  • Cloud Authentication — Password + OTP or Google OAuth login for cloud API access
  • Session Management — Token-based sessions with automatic refresh and rotation
  • Workspace Management — List, track, and stop active environments
  • Zero External Deps — Pure Python 3.9+ stdlib; only needs Docker and the Dev Container CLI
  • Modular Design — Clean separation of workspace, config, container, and orchestration layers

Explore