Skip to main content

​
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 a devcontainer.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
Configure environments in Settings (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

Parses devcontainer.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 gh CLI
  • 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
    • gh CLI installed (optional — needed for command execution and file sync)

​
Environment Lifecycle

Commander shows animated progress steps during provisioning so you can follow along.

​
Quick Actions

The environment panel provides quick-action buttons: Actions are disabled while the environment is transitioning between states.

​
Port Forwarding

Ports defined in devcontainer.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: Local Docker only: GitHub Codespaces only:

​
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 run gh 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>.