> ## Documentation Index
> Fetch the complete documentation index at: https://commander-docs.cyshel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

> Devcontainer and GitHub Codespaces support per workspace.

## 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](/features/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](https://www.docker.com/products/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

| 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                                      |

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

## 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) |

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**:

| 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 |

**Local Docker only:**

| Setting      | Default   | Description                                       |
| ------------ | --------- | ------------------------------------------------- |
| CPU Limit    | Unlimited | Maximum CPU cores allocated to the environment    |
| Memory Limit | Unlimited | Maximum memory in MB allocated to the environment |

**GitHub Codespaces only:**

| 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](https://www.docker.com/products/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](https://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>`.