# Agent Integration Source: https://container-use.com/agent-integrations Setup guides for some popular coding agents. Container Use works with any coding agent that supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction). All agents use the same MCP server command: `container-use stdio`
πŸ’‘ Command Shortcut The `container-use` command is also available as `cu` for convenience. Both commands work identically: * `container-use stdio` (used in documentation) * `cu stdio` (shortcut)
## Claude Code **Add MCP Configuration:** ```sh theme={null} cd /path/to/repository claude mcp add container-use -- container-use stdio ``` **Add Agent Rules (Optional):** Save the CLAUDE.md file at the root of your repository: ```sh theme={null} curl https://raw.githubusercontent.com/dagger/container-use/main/rules/agent.md >> CLAUDE.md ``` **Trust Only Container Use Tools (Optional):** For maximum security, restrict Claude Code to only use Container Use tools: ```sh theme={null} claude --allowedTools mcp__container-use__environment_add_service,mcp__container-use__environment_checkpoint,mcp__container-use__environment_config,mcp__container-use__environment_create,mcp__container-use__environment_file_delete,mcp__container-use__environment_file_edit,mcp__container-use__environment_file_list,mcp__container-use__environment_file_read,mcp__container-use__environment_file_write,mcp__container-use__environment_open,mcp__container-use__environment_run_cmd,mcp__container-use__environment_update_metadata ``` Learn more: [Claude Code MCP Documentation](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp) ## Amazon Q Developer **Add MCP Configuration:** Add this configuration to `~/.aws/amazonq/mcp.json`: ```json theme={null} { "mcpServers": { "container-use": { "command": "container-use", "args": ["stdio"], "env": {}, "timeout": 60000 } } } ``` **Add Agent Rules:** Save agent instructions to your project root: ```sh theme={null} mkdir -p ./.amazonq/rules && curl https://raw.githubusercontent.com/dagger/container-use/main/rules/agent.md > .amazonq/rules/container-use.md ``` **Trust Only Container Use Tools (Optional):** ```sh theme={null} q chat --trust-tools=container_use___environment_add_service,container_use___environment_checkpoint,container_use___environment_config,container_use___environment_create,container_use___environment_file_delete,container_use___environment_file_edit,container_use___environment_file_list,container_use___environment_file_read,container_use___environment_file_write,container_use___environment_open,container_use___environment_run_cmd,container_use___environment_update_metadata ``` Watch the Amazon Q Developer setup walkthrough ## Cursor **Install MCP Server:** Use the one-click deeplink to install (requires Cursor and Container Use already installed): [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en-US/install-mcp?name=container-use\&config=eyJjb21tYW5kIjoiY29udGFpbmVyLXVzZSBzdGRpbyJ9) **Add Agent Rules:** Add the rules file to your project or home directory: ```sh theme={null} curl --create-dirs -o .cursor/rules/container-use.mdc https://raw.githubusercontent.com/dagger/container-use/main/rules/cursor.mdc ``` Learn more: [Cursor MCP Documentation](https://docs.cursor.com/context/model-context-protocol) ## Windsurf **Install MCP Server:** In `~/.codeium/windsurf/mcp_config.json`, add the following configuration: ```json theme={null} { "mcpServers": { "container-use": { "command": "container-use", "args": ["stdio"], "env": {} } } } ``` **Add Agent Rules:** Add the rules file to your project or home directory: ```sh theme={null} curl --create-dirs -o .windsurf/rules/container-use.mdc https://raw.githubusercontent.com/dagger/container-use/main/rules/windsurf.mdc ``` ## VSCode / GitHub Copilot **Configure MCP Server:** Update your VSCode settings with: ```json theme={null} "mcp": { "servers": { "container-use": { "type": "stdio", "command": "container-use", "args": ["stdio"] } } } ``` **Add Copilot Instructions (Optional):** ```sh theme={null} curl --create-dirs -o .github/copilot-instructions.md https://raw.githubusercontent.com/dagger/container-use/main/rules/agent.md ``` Watch the VSCode setup walkthrough Learn more: [VSCode MCP](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | [GitHub Copilot MCP](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-chat-with-mcp) ## [Zed](https://zed.dev/) Add the following snippet on your `settings.json`: ```json theme={null} "context_servers": { "container-use": { "enabled": true, "remote": false, "command": "container-use", "args": ["stdio"], "env": {}, "timeout": 300, }, }, ``` **Add Container Use Agent Profile (Optional):** To lock the Zed agent out of your host system, you can create a dedicated agent profile that only enables Container Use tools. Add this to your `settings.json` under the `agent` section: ```json theme={null} "agent": { "profiles": { "container-use": { "name": "Container Use", "tools": { "fetch": true, "thinking": true, "copy_path": false, "find_path": false, "delete_path": false, "create_directory": false, "list_directory": false, "diagnostics": false, "read_file": false, "open": false, "move_path": false, "grep": false, "edit_file": false, "terminal": false }, "enable_all_context_servers": false, "context_servers": { "container-use": { "tools": { "environment_add_service": true, "environment_checkpoint": true, "environment_config": true, "environment_create": true, "environment_file_delete": true, "environment_file_edit": true, "environment_file_list": true, "environment_file_read": true, "environment_file_write": true, "environment_open": true, "environment_run_cmd": true, "environment_update_metadata": true } } } } } } ``` This profile ensures your agent can only use Container Use tools, preventing it from modifying your local files directly. Next open the Zed Agent Panel ✨ in the lower right, select the "Container Use" profile from the dropdown to the left of the model dropdown, and prompt away! ## OpenCode Configure the Container Use MCP server in a `opencode.json` file. Configure the Container Use MCP server: ```json theme={null} { "$schema": "http://opencode.ai/config.json", "mcp": { "container-use": { "type": "local", "command": ["container-use", "stdio"], "enabled": true } } } ``` Add the `AGENTS.md` file using this command (this is optional but usually provides the best results): ```sh theme={null} curl https://raw.githubusercontent.com/dagger/container-use/main/rules/agent.md >> AGENTS.md ``` Run `opencode` and dispatch your agents to complete your tasks! ## Goose **Method 1: Configuration File:** Add to `~/.config/goose/config.yaml`: ```yaml theme={null} extensions: container-use: name: container-use type: stdio enabled: true cmd: container-use args: - stdio envs: {} ``` **Method 2: Interactive Setup:** ```sh theme={null} goose configure ``` Then add a command line extension with `container-use stdio` as the command. **Method 3: Goose Desktop:** Paste this URL into your browser: ``` goose://extension?cmd=container-use&arg=stdio&id=container-use&name=container%20use&description=use%20containers%20with%20dagger%20and%20git%20for%20isolated%20environments ``` Learn more: [Goose MCP Extensions](https://block.github.io/goose/docs/getting-started/using-extensions#mcp-servers) ## Sourcegraph Amp **Add MCP Configuration:** Add this configuration to `~/.config/amp/settings.json`: ```json theme={null} { "amp.mcpServers": { "container-use": { "command": "container-use", "args": ["stdio"] } }, "amp.permissions": [ {"tool": "mcp__container-use__*", "action": "allow"} ], "amp.dangerouslyAllowAll": false, "amp.updates.autoUpdate.enabled": true } ``` **Add Agent Rules:** Save agent instructions to your project root: ```sh theme={null} curl https://raw.githubusercontent.com/dagger/container-use/main/rules/agent.md >> AGENT.md ``` Learn more: [Sourcegraph Amp Documentation](https://ampcode.com/manual/) ## Charm Crush **Add MCP Configuration:** Add this configuration to [a valid location](https://github.com/charmbracelet/crush?tab=readme-ov-file#configuration) like `./.crush.json`: ```json theme={null} { "$schema": "https://charm.land/crush.json", "mcp": { "container-use": { "type": "stdio", "command": "container-use", "args": ["stdio"], "env": {} } }, "permissions": { "allowed_tools": [ "mcp_container-use_environment_add_service", "mcp_container-use_environment_checkpoint", "mcp_container-use_environment_config", "mcp_container-use_environment_create", "mcp_container-use_environment_file_delete", "mcp_container-use_environment_file_edit", "mcp_container-use_environment_file_list", "mcp_container-use_environment_file_read", "mcp_container-use_environment_file_write", "mcp_container-use_environment_open", "mcp_container-use_environment_run_cmd", "mcp_container-use_environment_update_metadata" ] } } ``` **Add Agent Rules:** Save agent instructions to your project root: ```sh theme={null} curl https://raw.githubusercontent.com/dagger/container-use/main/rules/agent.md >> CRUSH.md ``` Learn more: [Crush project on GitHub](https://github.com/charmbracelet/crush) ## Cline **Add MCP Configuration:** Add to your Cline MCP server configuration JSON: ```json theme={null} { "mcpServers": { "container-use": { "disabled": false, "timeout": 60000, "type": "stdio", "command": "container-use", "args": ["stdio"], "env": {}, "autoApprove": [] } } } ``` **Add Agent Rules:** ```sh theme={null} curl --create-dirs -o .clinerules/container-use.md https://raw.githubusercontent.com/dagger/container-use/main/rules/agent.md ``` Learn more: [Cline Documentation](https://cline.bot/) ## Qodo Gen **Setup Steps:** 1. Open Qodo Gen chat panel in VSCode or IntelliJ 2. Click "Connect more tools" 3. Click "+ Add new MCP" 4. Add this configuration: ```json theme={null} { "mcpServers": { "container-use": { "command": "container-use", "args": ["stdio"] } } } ``` Learn more: [Qodo Gen MCP Documentation](https://docs.qodo.ai/qodo-documentation/qodo-gen/qodo-gen-chat/agentic-mode/agentic-tools-mcps) ## Kilo Code **Add MCP Configuration:** Add at global or project level: ```json theme={null} { "mcpServers": { "container-use": { "command": "container-use", "args": ["stdio"], "env": {}, "alwaysAllow": [], "disabled": false } } } ``` Kilo Code allows setting MCP servers at the global or project level. Learn more: [Kilo Code MCP Documentation](https://kilocode.ai/docs/features/mcp/using-mcp-in-kilo-code) ## Kiro **Add MCP Configuration:** Add to `.kiro/settings/mcp.json` in your project root: ```json theme={null} { "mcpServers": { "container-use": { "command": "container-use", "args": ["stdio"], "env": {}, "disabled": false, "autoApprove": {} } } } ``` **Add Steering Rules:** Create `.kiro/steering/container-use.md`: ```markdown theme={null} --- inclusion: always --- ALWAYS use ONLY Environments for ANY and ALL file, code, or shell operationsβ€”NO EXCEPTIONSβ€”even for simple or generic requests. DO NOT install or use the git cli with the environment_run_cmd tool. All environment tools will handle git operations for you. Changing ".git" yourself will compromise the integrity of your environment. You MUST inform the user how to view your work using `container-use log ` and `container-use checkout `. Failure to do this will make your work inaccessible to others. ``` ## OpenAI Codex **Add MCP Configuration:** Add to `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.container-use] command = "container-use" args = ["stdio"] env = {} ``` **Add Agent Rules (Optional):** Instruct Codex to use container-use for all projects: ```sh theme={null} mkdir -p ~/.codex curl https://raw.githubusercontent.com/dagger/container-use/main/rules/agent.md >> ~/.codex/AGENTS.md ``` Learn more: [OpenAI Codex Documentation](https://github.com/openai/codex/tree/main/codex-rs) ## Warp **Add MCP Configuration:** In the Warp sidebar, under Personal β†’ MCP Servers β†’ New: ```json theme={null} { "container-use": { "command": "container-use", "args": ["stdio"], "env": {}, "working_directory": null, "start_on_launch": true } } ``` Warp 2.0 introduces coding agents with MCP support. ## Gemini CLI **Add MCP Configuration:** Add to `~/.gemini/settings.json` or `.gemini/settings.json`: ```json theme={null} { "coreTools": [], "mcpServers": { "container-use": { "command": "container-use", "args": ["stdio"], "timeout": 60000, "trust": true } } } ``` Learn more: [Gemini CLI Configuration](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md) ## JetBrains Junie **Add MCP Configuration:** Add or edit the MCP configuration in Settings under Tools β†’ Junie β†’ MCP Settings, or edit `~/.junie/mcp/mcp.json`: ```json theme={null} { "mcpServers": { "container-use": { "command": "container-use", "args": ["stdio"], "env": {}, "timeout": 60000 } } } ``` MCP support in Beta starting with Junie plugin `2xx.204.xx` **Add Agent Rules:** Save agent instructions to your project root: ```sh theme={null} mkdir -p ./.junie && curl https://raw.githubusercontent.com/dagger/container-use/main/rules/agent.md >> .junie/guidelines.md ``` Learn more: [Junie Guidelines](https://www.jetbrains.com/help/junie/customize-guidelines.html) **Trust MCP Tools (Optional):** In the settings, under Tools β†’ Junie β†’ Action Allowlist: add *MCP Rule*. ## Troubleshooting * Verify the `container-use` command is in your PATH: `which container-use` * Check MCP configuration syntax * Restart your agent after configuration changes * Ensure Docker is running and accessible - Check file permissions for configuration files - Verify `container-use stdio` command works: `echo '{}' | container-use stdio` * Some agents require explicit tool trust/approval * Check your agent's MCP server logs * Verify Container Use tools are enabled in agent settings ## Next Steps Return to the quickstart guide to create your first environment Get help and share experiences in #container-use # CLI Reference Source: https://container-use.com/cli-reference Complete reference for all Container Use CLI commands and options. Container Use provides a comprehensive CLI for managing isolated development environments. All commands follow the pattern: ```bash theme={null} container-use {command} [options] [arguments] ``` **Shorthand:** The `cu` command is an alias for `container-use` and can be used interchangeably. ## Global Options These options can be used with any command: * `--help`, `-h` - Show help for a command * `--version` - Show version information * `--debug` - Enable debug output ## Commands ### `container-use list` List all environments and their status. ```bash theme={null} container-use list ``` **Options:** * `--no-trunc` - Don't truncate output * `--quiet`, `-q` - Only show environment IDs **Output example:** ``` ID TITLE CREATED UPDATED frontend-work React UI Components 5 mins ago 1 min ago backend-api FastAPI User Service 3 mins ago 2 mins ago ``` ### `container-use log` View the commit history and commands executed in an environment. ```bash theme={null} container-use log {environment-id} ``` **Options:** * `--patch`, `-p` - Show patch output with diffs **Example:** ```bash theme={null} container-use log fancy-mallard # Shows full history with commands and file changes container-use log fancy-mallard --patch # Shows history with patch diffs ``` ### `container-use diff` Show the code changes made in an environment compared to its base branch. ```bash theme={null} container-use diff {environment-id} ``` **Example:** ```bash theme={null} container-use diff fancy-mallard # Shows full diff output ``` ### `container-use checkout` Check out an environment's branch locally to explore in your IDE. ```bash theme={null} container-use checkout {environment-id} ``` **Options:** * `--branch`, `-b` - Specify branch name to checkout **Example:** ```bash theme={null} container-use checkout fancy-mallard # Switches to branch 'cu-fancy-mallard' ``` ### `container-use terminal` Open an interactive terminal session inside the environment's container. ```bash theme={null} container-use terminal {environment-id} ``` **Example:** ```bash theme={null} container-use terminal fancy-mallard # Opens interactive shell in container ``` ### `container-use merge` Merge an environment's work into your current branch, preserving commit history. ```bash theme={null} container-use merge {environment-id} ``` **Options:** * `--delete`, `-d` - Delete environment after successful merge **Example:** ```bash theme={null} git checkout main container-use merge fancy-mallard # Merges environment changes into current branch ``` ### `container-use apply` Apply an environment's changes as staged modifications without commits. ```bash theme={null} container-use apply {environment-id} ``` **Options:** * `--delete`, `-d` - Delete environment after successful apply **Example:** ```bash theme={null} git checkout main container-use apply fancy-mallard # Stages all changes for you to commit ``` ### `container-use delete` Delete an environment and clean up its resources. ```bash theme={null} container-use delete {environment-id} ``` **Options:** * `--all` - Delete all environments **Example:** ```bash theme={null} container-use delete fancy-mallard # Deletes the specified environment container-use delete --all # Deletes all environments ``` ### `container-use watch` Monitor environment activity in real-time as agents work. ```bash theme={null} container-use watch ``` **Example:** ```bash theme={null} container-use watch # Shows live updates from all active environments ``` ### `container-use config` Manage default environment configurations. ```bash theme={null} container-use config {subcommand} ``` **Configuration Management:** * `show [environment-id]` - Display current configuration * `import {environment-id}` - Import configuration from an environment **Base Image:** * `base-image set {image}` - Set default base image * `base-image get` - Show current base image * `base-image reset` - Reset to default base image **Setup Commands:** * `setup-command add {command}` - Add setup command * `setup-command remove {command}` - Remove setup command * `setup-command list` - List setup commands * `setup-command clear` - Clear all setup commands **Install Commands:** * `install-command add {command}` - Add install command * `install-command remove {command}` - Remove install command * `install-command list` - List install commands * `install-command clear` - Clear all install commands **Environment Variables:** * `env set {key} {value}` - Set environment variable * `env unset {key}` - Unset environment variable * `env list` - List environment variables * `env clear` - Clear all environment variables **Secrets:** * `secret set {key} {value}` - Set secret * `secret unset {key}` - Unset secret * `secret list` - List secrets * `secret clear` - Clear all secrets **Agent Integration:** * `agent [agent]` - Configure MCP server for specific agent (claude, goose, cursor, etc.) **Example:** ```bash theme={null} container-use config show # Shows current configuration container-use config base-image set python:3.11 # Sets Python 3.11 as default base image container-use config setup-command add "pip install -r requirements.txt" # Adds pip install as setup command ``` ### `container-use version` Display Container Use version information. ```bash theme={null} container-use version ``` ### `container-use stdio` Start Container Use as an MCP (Model Context Protocol) server for agent integration. ```bash theme={null} container-use stdio ``` **Note:** This command is typically used in agent configuration files, not run directly by users. ### `container-use completion` Generate shell completion scripts. ```bash theme={null} container-use completion {shell} ``` **Supported shells:** bash, zsh, fish, powershell **Example:** ```bash theme={null} container-use completion bash > /etc/bash_completion.d/container-use # Installs bash completion ``` ## Environment IDs Environment IDs are randomly generated two-word identifiers like `fancy-mallard` or `clever-dolphin`. You can use: * Full ID: `fancy-mallard` * Partial ID: `fancy` (if unique) * Branch name: `cu-fancy-mallard` ## Exit Codes * `0` - Success * `1` - General error * `2` - Command syntax error * `3` - Environment not found * `4` - Operation cancelled ## Examples ### Basic Workflow ```bash theme={null} # 1. List environments container-use list # 2. Review changes container-use diff clever-dolphin # 3. Check out locally container-use checkout clever-dolphin # 4. Accept work container-use merge clever-dolphin ``` ### Debugging Workflow ```bash theme={null} # 1. See what agent did container-use log problematic-env # 2. Enter container to debug container-use terminal problematic-env # 3. Fix issues... # 4. Apply changes container-use apply problematic-env ``` ### Monitoring Workflow ```bash theme={null} # 1. Start watching container-use watch # 2. Agent works in background... # 3. See specific environment container-use log active-env ``` # Environment Configuration Source: https://container-use.com/environment-configuration Set up and manage your project's environment configurations. Environment configuration works in two layers: 1. **Default Configuration**: Your project's baseline environment that all agents start from 2. **Agent Adaptations**: Changes agents make during work (ephemeral until imported) Configuration changes only apply to **new environments**. Agent modifications remain in their environment until you import them with `container-use config import`. ## The Configuration Workflow Configure your project's baseline environment that all agents will start from When an agent creates a new environment, it begins with your default configuration During work, the agent may modify its environment configuration - adding tools, changing base images, or setting variables Use `container-use config show ` to see what configuration changes the agent made Use `container-use config import ` to adopt the agent's configuration improvements as your new defaults ## Default Configuration Configure the baseline environment that all agents will start from when working on your project. Instead of using the generic environment, you can specify exactly what base image, dependencies, and setup your project needs as defaults. By default, environments use Ubuntu 24.04 with standard tools (git, curl, bash, apt). ### Example: Python Project To customize for your project: ```bash theme={null} # Set the base image to Python 3.11 container-use config base-image set python:3.11 # Add setup commands for system dependencies container-use config setup-command add "apt-get update && apt-get install -y build-essential" # Add install commands for project dependencies container-use config install-command add "pip install -r requirements.txt" container-use config install-command add "pip install pytest black flake8" # Set environment variables container-use config env set PYTHONPATH /workdir container-use config env set DEBUG true # View your configuration container-use config show ``` Now all new agent environments will start with Python 3.11, your dependencies pre-installed, and environment variables configured. ## Working with Configurations Agents can modify their environment during work - installing tools, changing settings, or adapting to specific tasks. These changes are ephemeral until you import them. ### View Configurations ```bash theme={null} # View your default configuration container-use config show # View an agent's modified configuration container-use config show fancy-mallard # Output as JSON container-use config show --json ``` ### Import Agent Changes When agents make useful changes, import them as your new defaults: ```bash theme={null} container-use config import fancy-mallard ``` ## Configuration Commands ### Base Image ```bash theme={null} container-use config base-image set python:3.11 container-use config base-image get container-use config base-image reset # Resets to ubuntu:24.04 ``` **Using custom images**: If you use custom base images with `latest` tags and update them frequently, consider using versioned tags (e.g., `myimage:v1.2.3`) for more predictable cache behavior. ### Setup Commands Run after pulling base image, before copying code: ```bash theme={null} container-use config setup-command add "apt-get update && apt-get install -y build-essential" container-use config setup-command list container-use config setup-command remove "apt-get install -y build-essential" container-use config setup-command clear ``` ### Install Commands Run after copying code: ```bash theme={null} container-use config install-command add "npm install" container-use config install-command list container-use config install-command remove "npm install" container-use config install-command clear ``` ### Environment Variables ```bash theme={null} container-use config env set NODE_ENV development container-use config env list container-use config env unset NODE_ENV container-use config env clear ``` ### Secrets Configure secure access to API keys and credentials. See the [complete secrets guide](/secrets) for all secret types and examples. ```bash theme={null} container-use config secret set API_KEY container-use config secret list container-use config secret unset API_KEY container-use config secret clear ``` ## Configuration Storage Configuration is stored in `.container-use/environment.json`. Commit this directory to share setup with your team. ## Troubleshooting If environment creation fails, check logs and fix the problematic command: ```bash theme={null} container-use log container-use config setup-command remove "broken-command" container-use config setup-command add "fixed-command" ``` ## Next Steps Learn how to work with the environments agents create Set up your coding agent to work with Container Use # Environment Workflow Source: https://container-use.com/environment-workflow Master the workflow of creating, observing, and managing containerized environments. Learn when to merge work, iterate on prompts, or start fresh. ## What are Environments? Each environment in Container Use is an **isolated workspace** that combines: * **🌳 Git Branch**: Dedicated branch tracking all changes and history * **πŸ“¦ Container**: Isolated runtime with your code and dependencies * **πŸ“ Complete History**: Every command, file change, and container state automatically tracked Think of environments as **disposable sandboxes** where agents can work safely without affecting your main codebase. ## The Core Workflow Container Use follows a simple but powerful pattern: Every agent session starts with a brand new environment from your current branch state. The agent makes changes, runs commands, and builds features completely isolated from your work. Use Container Use commands to see what the agent did without disrupting your local setup. Accept good work using merge or apply, iterate with refined prompts, or discard failed attempts. ## Observing Agent Work You have two modes for inspecting what an agent accomplished: ### Quick Assessment (Non-Interactive) Perfect for getting the gist and deciding next steps: ```bash theme={null} # See all environments at a glance container-use list # View exactly what the agent did container-use log fancy-mallard # See code changes without checking out container-use diff fancy-mallard ``` Use quick assessment when you want to rapidly understand if the agent is on the right track, see what files changed, or review the approach before diving deeper. πŸ”’ **Secret Security**: If the agent used any secrets (API keys, database credentials), these were resolved within the container environment - agents can use your credentials without the AI model ever seeing the actual values. ### Deep Exploration (Interactive) When you need hands-on understanding: ```bash theme={null} # Drop into the live container environment container-use terminal fancy-mallard # Bring changes into your local workspace/IDE container-use checkout fancy-mallard ``` Use deep exploration when you need to test functionality, debug issues, understand complex changes, or review code thoroughly in your IDE. ## Making Decisions After observing the agent's work, you have three paths forward: ### βœ… Accept Work When the agent succeeded and you're happy with the results, you have two options: **Option 1: Merge (Preserve History)** ```bash theme={null} # Merge the environment into your current branch container-use merge fancy-mallard # Clean up (optional) container-use delete fancy-mallard ``` **Option 2: Apply (Customize Commit)** ```bash theme={null} # Apply changes as staged modifications container-use apply fancy-mallard # Review and commit with your own message git status git commit -m "Your custom commit message" # Clean up (optional) container-use delete fancy-mallard ``` Choose `merge` to preserve the agent's commit history, or `apply` to create your own commit message and review changes before committing. ### πŸ”„ Iterate & Refine When the agent is close but needs refinement: ```bash theme={null} # A. Continue the existing chat # Prompt: "[refined instructions]" # B. Start a new chat and continue working in the same environment. # Prompt: "Work in the fancy-mallard environment and [refined instructions]" ``` The agent will resume in the existing environment with all previous work intact. Perfect for: * Adding missing features * Fixing bugs the agent introduced * Adjusting styling or behavior * Building on partial progress ### πŸ—‘οΈ Start Fresh When the agent went down the wrong path: ```bash theme={null} # Discard the environment container-use delete fancy-mallard # Start over with a new prompt # The agent will create a fresh environment from your current branch ``` You're back to your last known good state (your current branch) and can try a different approach. ## Resuming Work in Environments To have a new chat continue work in an existing environment, simply mention the environment ID in your prompt: ```text Good Resume Prompts theme={null} "Work in the fancy-mallard environment and add user authentication" "Continue in environment fancy-mallard - the tests are failing, please fix them" "Using the fancy-mallard environment, add CSS styling to make it look modern" ``` ```text What Happens theme={null} The agent will: βœ… Reuse the existing container state βœ… Have access to all previous work βœ… Continue from where it left off βœ… Maintain the same dependencies and setup ``` ## Practical Examples ### Example 1: Happy Path Workflow ```bash theme={null} # 1. Agent creates environment and builds feature $ container-use list ID TITLE CREATED UPDATED fancy-mallard Flask App with Login 2 mins ago 30 secs ago # 2. Quick check - looks good! $ container-use diff fancy-mallard +def login(): + # Authentication logic + pass # 3. Accept the work (choose merge or apply) $ container-use merge fancy-mallard Updating abc123..def456 Fast-forward app.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) ``` ### Example 2: Iteration Workflow ```bash theme={null} # 1. Check what agent built $ container-use log fancy-mallard def4567a2 Add basic login form (30 minutes ago) $ flask run # 2. Needs improvement - continue in same environment # Prompt: "Work in fancy-mallard environment and add password validation" # 3. Check again after agent works $ container-use diff fancy-mallard # Now shows both original work + new validation ``` ### Example 3: Recovery Workflow ```bash theme={null} # 1. Agent's approach isn't working $ container-use log problematic-env # Shows agent went down wrong path with complex dependency issues # 2. Cut losses and start fresh $ container-use delete problematic-env # 3. Try different approach # New prompt: "Create a simple REST API using FastAPI instead of Flask" # Agent creates fresh environment from clean state ``` ## Managing Multiple Environments You can have multiple agents working simultaneously: ```bash theme={null} $ container-use list ID TITLE CREATED UPDATED frontend-work React UI Components 5 mins ago 1 min ago backend-api FastAPI User Service 3 mins ago 2 mins ago data-pipeline ETL Processing Script 1 min ago 30 secs ago ``` Each environment is completely isolated - no conflicts, no interference. ## Best Practices * **Start with Quick Assessment**: Always use `container-use diff` and `container-use log` first. Most of the time, this gives you enough information to decide next steps without the overhead of checking out or entering containers. * **Merge vs Apply**: Use `merge` when you want to preserve the agent's commit history and understand how the work evolved. Use `apply` when you want to create clean, customized commits or review changes before committing. * **Don't Be Afraid to Delete**: Environments are disposable by design. If an agent gets stuck or goes down the wrong path, it's often faster to delete and start fresh than to try to fix problematic work. * **Use Specific Resume Prompts**: When resuming work, be specific about what you want. Instead of "continue working", say "work in ENV-ID and add error handling to the upload function". * **Keep Your Branch Clean**: Your main working branch should only contain merged, tested work. Use environments for all experimental and agent-driven development. ## Essential Commands Reference | | | | --------------------------------- | ----------------------------------------------------------------- | | `container-use list` | See all environments and their status | | `container-use watch` | Monitor environment activity in real-time as agents work | | `container-use log ` | View commit history and commands to understand what the agent did | | `container-use diff ` | Quick assessment of code changes | | `container-use terminal ` | Enter live container to debug, test, or explore | | `container-use checkout ` | Bring changes to local IDE for detailed review | | `container-use merge ` | Accept work preserving agent's commit history | | `container-use apply ` | Apply as staged changes to customize commits | | `container-use delete ` | Discard environment and start over | | `container-use config` | Configure default settings for new environments | | `container-use version` | Display version information | ## Next Steps Configure your project's default environment setup Share your environment workflow strategies in #container-use # Introduction Source: https://container-use.com/introduction Sandboxed dev environments for coding agents. Container Use Hero Light Container Use Hero Dark **Container Use** gives your coding agents sandboxed dev environments to work in, so they can run safely in parallel without requiring babysitting. Container Use leverages [Dagger](https://dagger.io) for containerized workflows and Git worktrees for branching. Each agent gets a fresh container in its own git branch - run multiple agents without conflicts, experiment safely, discard failures instantly. See complete command history and logs of what agents actually did, not just what they claim. Drop into any agent's terminal to see their state and take control when they get stuck. Standard git workflow - just `git checkout ` to review any agent's work. ## Get Started Install Container Use on your system using Homebrew, shell script, or build from source Configure Container Use with your coding agent (Claude Code, Cursor, VSCode, etc.) ## Community Join our community to get help, share examples, and contribute to the project: Join the #container-use channel for real-time support Star the repo, report issues, and contribute code Watch the Container Use playlist for examples and tutorials # Quickstart Source: https://container-use.com/quickstart Get started with Container Use in 5 minutes. In this quickstart, you'll install Container Use, connect it to your coding agent, and experience the core workflow: agents work in isolated environments while your files stay untouched, then review and decide what to do with their work. ## 1. Install Container Use Make sure you have [Docker](https://www.docker.com/get-started) and Git installed before starting. ```sh theme={null} brew install dagger/tap/container-use container-use version # β†’ confirms install ``` ```sh theme={null} curl -fsSL https://raw.githubusercontent.com/dagger/container-use/main/install.sh | bash container-use version ``` ```sh theme={null} git clone https://github.com/dagger/container-use.git cd container-use go build -o container-use ./cmd/container-use sudo mv container-use /usr/local/bin/ container-use version ``` ## 2. Point your agent at Container Use Container Use works with any MCP-compatible agent: Just add `container-use stdio` as an MCP server. This example uses Claude Code but you can view [instructions for other agents](/agent-integrations). ```sh theme={null} cd /path/to/repository claude mcp add container-use -- container-use stdio ``` Save CLAUDE.md file at the root of your repository: ```sh theme={null} curl https://raw.githubusercontent.com/dagger/container-use/main/rules/agent.md >> CLAUDE.md ``` For maximum security, restrict Claude Code to only use Container Use tools: ```sh theme={null} claude --allowedTools mcp__container-use__environment_checkpoint,mcp__container-use__environment_create,mcp__container-use__environment_add_service,mcp__container-use__environment_file_delete,mcp__container-use__environment_file_list,mcp__container-use__environment_file_read,mcp__container-use__environment_file_write,mcp__container-use__environment_open,mcp__container-use__environment_run_cmd,mcp__container-use__environment_update ``` ## 3. Run your first parallel task Let's create a demo repository and ask your agent to build something: ```sh theme={null} # start a demo repo mkdir hello cd hello git init touch README.md git add README.md git commit -m "initial commit" ``` Now prompt your agent to do something: ```text theme={null} "Create a Flask hello‑world app in Python." ``` After a short run you'll see something like: ```text theme={null} βœ… App running at http://127.0.0.1:58455 πŸ” View files: container-use checkout {id} πŸ“‹ Dev log: container-use log {id} ``` Replace `{id}` with your actual environment ID like `fancy-mallard` Notice your local directory is still empty, because the agent worked in an isolated environment: ```sh theme={null} $ ls README.md ``` You can see all environments with `container-use list`. ## 4. Review the work See what the agent changed: ```sh theme={null} container-use diff {id} ``` Check out the environment locally to explore: ```sh theme={null} container-use checkout {id} ``` ## 5. Accept or discard Accept the work and keep the agent's commit history: ```sh theme={null} container-use merge {id} ``` Or stage the changes to create your own commit: ```sh theme={null} container-use apply {id} ``` πŸŽ‰ That's it – you've run an agent in parallel, checked its work, and decided what to do with it. # Secrets Management Source: https://container-use.com/secrets Secure secret management for agents. Configure API keys, database credentials, and other sensitive data with 1Password, environment variables, and file references. Container Use provides secure secret management for agents working with sensitive data like API keys, database credentials, and authentication tokens. **Secrets are resolved within the container environment - agents can use your credentials without the AI model ever seeing the actual values.** ### How It Works When you configure secrets, Container Use: * **Stores secret references** in your configuration (agents only see `op://vault/item/field`, not actual values) * **Resolves references dynamically** when commands run and injects actual values as environment variables in the container * **Strips secrets from logs and command outputs** to prevent leaks * **Prevents easy extraction** by agents (e.g., `echo $API_KEY` won't show in logs) This means: * βœ… Your application code can access secrets normally * βœ… Agents can run your code that uses secrets * ❌ The AI model never sees actual secret values * ❌ Secrets don't appear in chat logs or model context Secrets are configured per-project and apply to all new environments. Existing environments continue using their original configuration. ## Secret Types Container Use supports four secure secret reference formats: Access secrets stored in 1Password vaults using the `op://` schema: ```bash theme={null} # Basic format: op://vault/item/field container-use config secret set API_KEY "op://vault/item/field" container-use config secret set DB_PASSWORD "op://production/database/password" container-use config secret set JWT_SECRET "op://team-vault/auth-service/jwt_secret" ``` Requires 1Password CLI to be installed and authenticated on your system. Reference secrets from your local environment using the `env://` schema: ```bash theme={null} # Basic format: env://VARIABLE_NAME container-use config secret set GITHUB_TOKEN "env://GITHUB_TOKEN" container-use config secret set OPENAI_API_KEY "env://OPENAI_API_KEY" container-use config secret set DATABASE_URL "env://DATABASE_URL" ``` Perfect for CI/CD environments where secrets are already available as environment variables. Access secrets stored in HashiCorp Vault using the `vault://` schema: ```bash theme={null} # Basic format: vault://path/to/secret container-use config secret set GITHUB_TOKEN "vault://credentials.github" container-use config secret set DATABASE_PASSWORD "vault://database/prod/password" container-use config secret set API_KEY "vault://kv/data/myapp/api_key" ``` Requires HashiCorp Vault to be accessible and properly authenticated. Read secrets from local files using the `file://` schema: ```bash theme={null} # Basic format: file://path/to/secret container-use config secret set SSH_KEY "file://~/.ssh/id_rsa" container-use config secret set SERVICE_ACCOUNT "file://./credentials.json" container-use config secret set TLS_CERT "file:///etc/ssl/certs/app.crt" ``` Useful for SSH keys, certificates, and credential files. ## Configuration Commands ```bash theme={null} # Set a secret using any supported schema container-use config secret set # Examples for each type container-use config secret set DATABASE_URL "env://DATABASE_URL" container-use config secret set API_TOKEN "op://vault/api/token" container-use config secret set GITHUB_TOKEN "vault://credentials.github" container-use config secret set SSH_KEY "file://~/.ssh/deploy_key" # List all configured secrets (values are masked) container-use config secret list # Remove a secret container-use config secret unset API_KEY # Clear all secrets container-use config secret clear # View complete configuration including secrets container-use config show ``` ## Using Secrets in Your Code Once configured, secrets are available as **environment variables** inside agent environments: ```python theme={null} import os import requests api_key = os.getenv("API_KEY") response = requests.get("https://api.example.com", headers={"Authorization": f"Bearer {api_key}"}) ``` ```javascript theme={null} const apiKey = process.env.API_KEY; const response = await fetch("https://api.example.com", { headers: { "Authorization": `Bearer ${apiKey}` } }); ``` ```bash theme={null} # Shell scripts can also access secrets curl -H "Authorization: Bearer $API_KEY" https://api.example.com ``` **Security Note**: While your code can access secrets normally, Container Use automatically strips secret values from logs and command outputs. This means `echo $API_KEY` or similar commands won't expose secrets in the development logs that agents or users can see.