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:
Agent Creates Fresh Environment
Every agent session starts with a brand new environment from your current branch state.
Agent Works in Isolation
The agent makes changes, runs commands, and builds features completely isolated from your work.
You Observe the Work
Use Container Use commands to see what the agent did without disrupting your local setup.
Make a Decision
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:
When to use
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:
When to use
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:
When the agent succeeded and you’re happy with the results, you have two options:
Option 1: Merge (Preserve History)
Option 2: Apply (Customize Commit)
Choose merge to preserve the agent’s commit history, or apply to create your own commit message and review changes before committing.
When the agent succeeded and you’re happy with the results, you have two options:
Option 1: Merge (Preserve History)
Option 2: Apply (Customize Commit)
Choose merge to preserve the agent’s commit history, or apply to create your own commit message and review changes before committing.
When the agent is close but needs refinement:
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
When the agent went down the wrong path:
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:
Practical Examples
Example 1: Happy Path Workflow
Example 2: Iteration Workflow
Example 3: Recovery Workflow
Managing Multiple Environments
You can have multiple agents working simultaneously:
Each environment is completely isolated - no conflicts, no interference.
Best Practices
Start with Quick Assessment
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.
Choose the Right Acceptance Method
Choose the Right Acceptance Method
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
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
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
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
| Command | Purpose | When to Use |
|---|
| container-use list | See all environments | Check status of agent work |
| container-use log <env-id> | View commit history + commands | Understand what agent did |
| container-use diff <env-id> | See code changes | Quick assessment of changes |
| container-use terminal <env-id> | Enter live container | Debug, test, hands-on exploration |
| container-use checkout <env-id> | Bring changes to local IDE | Detailed code review |
| container-use merge <env-id> | Accept work preserving history | When you want agent’s commit history |
| container-use apply <env-id> | Apply as staged changes | When you want to customize commits |
| container-use delete <env-id> | Discard environment | When starting over |