Codespace Manager

Manage isolated code-server development environments, similar to GitHub Codespaces. Each codespace runs in its own Docker container with a full VS Code editor accessible via browser through Cloudflare Tunnel.

Pre-installed Tools

The custom Docker image includes:

code-server (VS Code in browser)
Bun — JS/TS runtime + package manager
uv — Python package manager + virtual environments
OpenCode — AI coding assistant (CLI)
git, curl, wget, build-essential

First-Time Setup

Before creating any codespace, build the Docker image once:

bash scripts/codespace.sh setup

This builds codespace-manager:latest from assets/Dockerfile.txt. Only needed once per host.

Commands

Script location: scripts/codespace.sh (relative to this skill's directory)

# One-time image build
codespace setup

# Create codespace (optionally clone a repo and/or init OpenCode config)
codespace create <name>
codespace create <name> --git <repo-url>
codespace create <name> --opencode
codespace create <name> --git <repo-url> --opencode

# Lifecycle
codespace start <name>       # Start and get Cloudflare Tunnel URL
codespace stop <name>        # Stop container and tunnel
codespace restart <name>     # Stop then start (new URL)
codespace delete <name>      # Remove container + data (irreversible!)

# Info
codespace list               # List all codespaces with status
codespace status <name>      # Detailed status of one codespace
codespace logs <name>        # View container logs
codespace url <name>         # Regenerate tunnel URL

# Config
codespace password <pass>    # Set default password for new codespaces

Password Management

Default password: codespace
Set a custom default: codespace password <your-password>
Override per-session via environment: CODESPACE_PASSWORD=mypass codespace create foo
Each codespace saves its password at creation time

Natural Language → Command Mapping

User says	Command
"create a codespace called myapp"	`codespace create myapp`
"create a codespace with opencode"	`codespace create <name> --opencode`
"set up a dev environment for this repo"	`codespace create <name> --git <url> --opencode`
"start / launch / open myapp"	`codespace start myapp`
"stop / shut down myapp"	`codespace stop myapp`
"delete / remove myapp"	`codespace delete myapp` (confirm with user first!)
"list my codespaces" / "show environments"	`codespace list`
"get the URL for myapp"	`codespace url myapp`
"set password to xyz"	`codespace password xyz`
"create a python project"	`codespace create <name> --opencode` (uv is pre-installed)
"create a node/bun project"	`codespace create <name> --opencode` (bun is pre-installed)

Architecture

Each codespace = isolated Docker container (codespace-manager:latest)
Project files persist at ~/codespaces/<name>/project on the host
Exposed via Cloudflare Quick Tunnel (free, auto HTTPS, temporary URL)
Each codespace gets a deterministic port (9000-9999, based on name hash)

Important Notes

Run codespace setup before first use — it builds the Docker image
Quick Tunnel URLs are temporary — they change on restart
codespace delete is irreversible — confirm with user before executing
Container data (outside /home/coder/project) does not persist across delete/recreate
Requires: Docker, cloudflared, jq installed on the host

OpenCode Config

When --opencode is used, a opencode.json is created in the project root with:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true
}

Users can edit this file in code-server to change the model or add provider keys.