Overview
Commander can provision managed development environments for each workspace, giving your agents a place to build, test, and run code. Environments are configured per-repository and provisioned from adevcontainer.json in your repository.
Two modes are available:
- Local Docker — Builds and runs the devcontainer on your machine using Docker Desktop
- GitHub Codespaces — Creates a cloud-based codespace on GitHub’s infrastructure
Cmd+Shift+P) → select your repository → Environments.
Environment Modes
None (Default)
No managed environment. You can still add individual Docker containers manually to workspaces (see Containers).Local Docker
Parsesdevcontainer.json from your repository and runs the environment locally:
- Builds the Docker image from a Dockerfile or Docker Compose configuration
- Runs devcontainer lifecycle hooks (
onCreateCommand,postCreateCommand,postStartCommand) - Forwards ports defined in the devcontainer config
- Mounts the workspace worktree into the container
- Supports CPU and memory resource limits
- Requires Docker Desktop to be installed and running
GitHub Codespaces
Creates a GitHub Codespace from the workspace’s branch:- Pushes the workspace branch to the remote before creating the codespace
- Machine type selection from 2-core (8 GB RAM) through 32-core (128 GB RAM)
- Configurable idle timeout (default: 30 minutes)
- Automatic port forwarding via the
ghCLI - Prerequisites are validated automatically — Commander shows a checklist until all are met:
- GitHub account connected (Settings → Integrations)
- Repository has a GitHub remote
- Codespaces enabled on the repository or organization
ghCLI installed (optional — needed for command execution and file sync)
Environment Lifecycle
| Status | Description |
|---|---|
| Provisioning | Pushing branch (Codespaces) or preparing build context (Local) |
| Building | Docker image building or codespace initializing |
| Starting | Container launching or codespace starting up |
| Running | Environment active and healthy |
| Degraded | One or more components reporting unhealthy |
| Stopped | Environment shut down gracefully |
| Errored | Provisioning or runtime failure — see error guidance below |
| Destroying | Environment being removed |
Quick Actions
The environment panel provides quick-action buttons:| Action | Description |
|---|---|
| Start | Launch a stopped or errored environment |
| Stop | Gracefully shut down a running environment |
| Restart | Stop and start the environment |
| Rebuild | Tear down and rebuild from scratch (useful after devcontainer config changes) |
Port Forwarding
Ports defined indevcontainer.json are automatically forwarded:
- Forwarded ports appear in the environment panel with their container and host port numbers
- Click the copy icon to copy the local URL to your clipboard
- Click the open icon to open the URL in your default browser
- Enable Offset Ports on Conflict in settings to auto-assign different local ports when multiple environments use the same container ports
Component Health
For environments with multiple containers (e.g., Docker Compose setups), the environment panel shows each component:- Status dot (green = running, red = errored/unhealthy, gray = stopped)
- Container name and current status
- The primary container is marked with a “(primary)” label
Settings
Configure per-repository in Settings → Environments:| Setting | Default | Description |
|---|---|---|
| Environment Mode | None | How to provision environments: None, Local Docker, or GitHub Codespace |
| Auto-Provision | Off | Automatically create the environment when a new workspace is created |
| Devcontainer Config | Auto-detect | Path to devcontainer.json — auto-detected if only one exists in the repo |
| Volume Persistence | On | Keep data volumes across environment rebuilds |
| Offset Ports on Conflict | On | Auto-assign different local ports when multiple environments use the same ports |
| Setting | Default | Description |
|---|---|---|
| CPU Limit | Unlimited | Maximum CPU cores allocated to the environment |
| Memory Limit | Unlimited | Maximum memory in MB allocated to the environment |
| Setting | Default | Description |
|---|---|---|
| Machine Type | 2-core (8 GB) | Codespace VM size — options range from 2-core to 32-core |
| Idle Timeout | 30 minutes | Minutes of inactivity before the codespace automatically stops |
Error Guidance
When provisioning fails, Commander shows a smart error card with an explanation and actionable fix steps. Common errors: Docker Not Available Install and start Docker Desktop, then retry. GitHub Not Connected Go to Settings → Integrations and connect your GitHub account. Codespaces Not Enabled Enable Codespaces in your GitHub organization or repository settings, then retry. Branch Not on Remote Push the workspace branch to GitHub before creating a codespace. Commander attempts this automatically, but it can fail if the remote is not configured. gh CLI Not Installed Install the GitHub CLI from cli.github.com and rungh auth login to authenticate. The gh CLI is optional but required for running commands and syncing files inside codespaces.
No GitHub Remote
Add a GitHub remote to your repository: git remote add origin <url>.