---
title: "Environments"
description: "An **environment** is an isolated, containerized development workspace that combines Docker containers with Git branches to provide agents with safe, persistent workspaces."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/readme-285
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:36:20.768Z
license: CC-BY-4.0
attribution: "Environments — Claudary (https://claudary.paisolsolutions.com/skills/readme-285)"
---

# Environments
An **environment** is an isolated, containerized development workspace that combines Docker containers with Git branches to provide agents with safe, persistent workspaces.

## Overview

# Environments

An **environment** is an isolated, containerized development workspace that combines Docker containers with Git branches to provide agents with safe, persistent workspaces.

## What is an Environment?

Each environment consists of:
- **Git Branch**: Dedicated branch tracking all changes and history
- **Container**: Dagger container with your code and dependencies
- **History**: Versioned snapshots of container state changes appended to the branch as notes
- **Configuration**: Base image, setup commands, secrets, and instructions that can be checked into the source repo.

## Key Features

- **Branch-Based**: Each environment is a Git branch that syncs into the container-use/ remote
- **Isolation**: Each environment runs in its own container and branch
- **Persistence**: All changes automatically committed with full history
- **Standard Git**:
  - Use `git log` to view source code history
  - Use `git log --notes=container-use` to view container operation history
  - Use `git checkout env-branch` to inspect any environment's work - each env branch tracks the upstream container-use/
- **State Recovery**: Container states stored in Git notes for reconstruction

## How It Works

When you create an environment, container-use:

1. **Creates a new Git branch** in your source repo (e.g., `env-name/adverb-animal`)
2. **Sets up a container-use remote branch** inside `~/.config/container-use/repos/project/`
3. **Sets up a worktree copy of the branch** in `~/.config/container-use/worktrees/project/`
4. **Spins up a Dagger container** with that worktree copied into `/workdir`

When an agent runs commands:

1. **Commands execute** inside the isolated container
2. **File changes get written** back to the container filesystem
3. **Container state is preserved** in the Dagger container's LLB definition
4. **Everything gets committed** to the environment's Git branch automatically
5. **Container state snapshots** are stored as Git notes using `container-use-state` ref
6. **Operation logs** are stored as Git notes using `container-use` ref

Each environment is just a Git branch that your source repo tracks on the container-use/ remote. You can inspect any environment's work using standard Git commands, and the container state can always be reconstructed from an environment branch's Git history and notes.

## Architecture

```
projectName/ Source Repo                container-use/ Remote
├── feature-branch ←──── cu merge/apply ────────┐
├── main (current) ── environment_create ──→ adverb-animal
└── cu-adverb-animal ←──── cu checkout ───────────┘
                                       │
                                       │ (host filesystem implementation)
                                       ▼
                    ~/.config/container-use/
                    ├── repos/projectName/ (bare)
                    └── worktrees/adverb-animal (only env branches become worktrees)
                        ├── .git -> ../../repos/projectName/worktrees/adverb-animal
                        └── (your code)
                            │
                            ▼
                        Container
                        └── /workdir
```

The diagram shows how environment branches sync between your source repo and the container-use remote. When you create an environment, the current branch content gets pushed to the container-use remote as `adverb-animal`. When you checkout an environment, it creates a local tracking branch `cu-adverb-animal` that tracks the remote environment branch. Regular branches like `main` and `feature-branch` stay only in your source repo.

You can accept the environment's work into your current branch using either:
- **`cu merge`** - Preserves the agent's commit history
- **`cu apply`** - Stages changes for you to commit with your own message

Below the branch level, the system creates a bare Git repository and worktree in `~/.config/container-use/` - this is plumbing to make the Git operations work with minimal modifications to your source repository. The worktree contains a copy of your code that gets mounted into the Docker container at `/workdir`.

So the flow is: **Branch** (the logical environment) → **Worktree** (filesystem implementation) → **Container** (where code actually runs).

## Files

- `environment.go` - Core environment management and container operations
- `config.go` - Configuration management and persistence
- `state.go` - Container state serialization and legacy migration
- `service.go` - Service management for multi-container environments
- `note.go` - Git notes management for operation logging
- `filesystem.go` - File operations within containers
- `../repository/git.go` - Worktree and Git integration
- `../repository/repository.go` - High-level repository operations

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/readme-285) · https://claudary.paisolsolutions.com