Skip to content

Commit b1f20ab

Browse files
aluzzardicwlbraa
aluzzardi
and
cwlbraa
authored
docs: add a managing environments guide (#145)
* docs: add a managing environments guide Signed-off-by: Andrea Luzzardi <[email protected]> * Update docs/managing-environments.mdx Co-authored-by: Connor Braa <[email protected]> Signed-off-by: Andrea Luzzardi <[email protected]> * Update docs/managing-environments.mdx Co-authored-by: Connor Braa <[email protected]> Signed-off-by: Andrea Luzzardi <[email protected]> --------- Signed-off-by: Andrea Luzzardi <[email protected]> Signed-off-by: Andrea Luzzardi <[email protected]> Co-authored-by: Connor Braa <[email protected]>
1 parent 0fb7f45 commit b1f20ab

File tree

2 files changed

+278
-1
lines changed

2 files changed

+278
-1
lines changed

‎docs/docs.json

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,13 @@
1919
"introduction",
2020
"quickstart"
2121
]
22-
},
22+
},
23+
{
24+
"group": "Guides",
25+
"pages": [
26+
"managing-environments"
27+
]
28+
},
2329
{
2430
"group": "Integrations",
2531
"pages": [

‎docs/managing-environments.mdx

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
---
2+
title: Managing Environments
3+
description: "Master the workflow of creating, observing, and managing containerized environments. Learn when to merge work, iterate on prompts, or start fresh."
4+
icon: gear
5+
---
6+
7+
## What are Environments?
8+
9+
Each environment in Container Use is an **isolated workspace** that combines:
10+
11+
- **🌳 Git Branch**: Dedicated branch tracking all changes and history
12+
- **📦 Container**: Isolated runtime with your code and dependencies
13+
- **📝 Complete History**: Every command, file change, and container state automatically tracked
14+
15+
Think of environments as **disposable sandboxes** where agents can work safely without affecting your main codebase.
16+
17+
## The Core Workflow
18+
19+
Container Use follows a simple but powerful pattern:
20+
21+
<Steps>
22+
<Step title="Agent Creates Fresh Environment">
23+
Every agent session starts with a brand new environment from your current branch state.
24+
</Step>
25+
<Step title="Agent Works in Isolation">
26+
The agent makes changes, runs commands, and builds features completely isolated from your work.
27+
</Step>
28+
<Step title="You Observe the Work">
29+
Use Container Use commands to see what the agent did without disrupting your local setup.
30+
</Step>
31+
<Step title="Make a Decision">
32+
Merge good work, iterate with refined prompts, or discard failed attempts.
33+
</Step>
34+
</Steps>
35+
36+
## Observing Agent Work
37+
38+
You have two modes for inspecting what an agent accomplished:
39+
40+
### Quick Assessment (Non-Interactive)
41+
42+
Perfect for getting the gist and deciding next steps:
43+
44+
```bash
45+
# See all environments at a glance
46+
cu list
47+
48+
# View exactly what the agent did
49+
cu log fancy-mallard
50+
51+
# See code changes without checking out
52+
cu diff fancy-mallard
53+
```
54+
55+
<Card title="When to use" icon="eye">
56+
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.
57+
</Card>
58+
59+
### Deep Exploration (Interactive)
60+
61+
When you need hands-on understanding:
62+
63+
```bash
64+
# Drop into the live container environment
65+
cu terminal fancy-mallard
66+
67+
# Bring changes into your local workspace/IDE
68+
cu checkout fancy-mallard
69+
```
70+
71+
<Card title="When to use" icon="magnifying-glass">
72+
Use deep exploration when you need to test functionality, debug issues, understand complex changes, or review code thoroughly in your IDE.
73+
</Card>
74+
75+
## Making Decisions
76+
77+
After observing the agent's work, you have three paths forward:
78+
79+
<Tabs>
80+
<Tab title="✅ Accept Work">
81+
When the agent succeeded and you're happy with the results:
82+
83+
```bash
84+
# Merge the environment into your current branch
85+
cu merge fancy-mallard
86+
87+
# Clean up (optional)
88+
cu delete fancy-mallard
89+
```
90+
91+
The work becomes part of your Git history and you can continue from this new state.
92+
93+
</Tab>
94+
95+
<Tab title="🔄 Iterate & Refine">
96+
When the agent is close but needs refinement:
97+
98+
```bash
99+
# A. Continue the existing chat
100+
# Prompt: "[refined instructions]"
101+
# B. Start a new chat and continue working in the same environment.
102+
# Prompt: "Work in the fancy-mallard environment and [refined instructions]"
103+
```
104+
105+
The agent will resume in the existing environment with all previous work intact. Perfect for:
106+
- Adding missing features
107+
- Fixing bugs the agent introduced
108+
- Adjusting styling or behavior
109+
- Building on partial progress
110+
111+
</Tab>
112+
113+
<Tab title="🗑️ Start Fresh">
114+
When the agent went down the wrong path:
115+
116+
```bash
117+
# Discard the environment
118+
cu delete fancy-mallard
119+
120+
# Start over with a new prompt
121+
# The agent will create a fresh environment from your current branch
122+
```
123+
124+
You're back to your last known good state (your current branch) and can try a different approach.
125+
126+
</Tab>
127+
</Tabs>
128+
129+
## Resuming Work in Environments
130+
131+
To have a new chat continue work in an existing environment, simply mention the environment ID in your prompt:
132+
133+
<CodeGroup>
134+
```text Good Resume Prompts
135+
"Work in the fancy-mallard environment and add user authentication"
136+
137+
"Continue in environment fancy-mallard - the tests are failing, please fix them"
138+
139+
"Using the fancy-mallard environment, add CSS styling to make it look modern"
140+
```
141+
142+
```text What Happens
143+
The agent will:
144+
✅ Reuse the existing container state
145+
✅ Have access to all previous work
146+
✅ Continue from where it left off
147+
✅ Maintain the same dependencies and setup
148+
```
149+
</CodeGroup>
150+
151+
## Practical Examples
152+
153+
### Example 1: Happy Path Workflow
154+
155+
```bash
156+
# 1. Agent creates environment and builds feature
157+
$ cu list
158+
ID TITLE CREATED UPDATED
159+
fancy-mallard Flask App with Login 2 mins ago 30 secs ago
160+
161+
# 2. Quick check - looks good!
162+
$ cu diff fancy-mallard
163+
+def login():
164+
+ # Authentication logic
165+
+ pass
166+
167+
# 3. Accept the work
168+
$ cu merge fancy-mallard
169+
Updating abc123..def456
170+
Fast-forward
171+
app.py | 15 +++++++++++++++
172+
1 file changed, 15 insertions(+)
173+
```
174+
175+
### Example 2: Iteration Workflow
176+
177+
```bash
178+
# 1. Check what agent built
179+
$ cu log fancy-mallard
180+
commit def456 (container-use/fancy-mallard)
181+
Author: Agent <[email protected]>
182+
Date: Mon Jan 15 10:30:00 2024 -0800
183+
184+
Add basic login form
185+
186+
Notes (container-use):
187+
$ flask run
188+
189+
# 2. Needs improvement - continue in same environment
190+
# Prompt: "Work in fancy-mallard environment and add password validation"
191+
192+
# 3. Check again after agent works
193+
$ cu diff fancy-mallard
194+
# Now shows both original work + new validation
195+
```
196+
197+
### Example 3: Recovery Workflow
198+
199+
```bash
200+
# 1. Agent's approach isn't working
201+
$ cu log problematic-env
202+
# Shows agent went down wrong path with complex dependency issues
203+
204+
# 2. Cut losses and start fresh
205+
$ cu delete problematic-env
206+
207+
# 3. Try different approach
208+
# New prompt: "Create a simple REST API using FastAPI instead of Flask"
209+
# Agent creates fresh environment from clean state
210+
```
211+
212+
## Managing Multiple Environments
213+
214+
You can have multiple agents working simultaneously:
215+
216+
```bash
217+
$ cu list
218+
ID TITLE CREATED UPDATED
219+
frontend-work React UI Components 5 mins ago 1 min ago
220+
backend-api FastAPI User Service 3 mins ago 2 mins ago
221+
data-pipeline ETL Processing Script 1 min ago 30 secs ago
222+
```
223+
224+
Each environment is completely isolated - no conflicts, no interference.
225+
226+
## Best Practices
227+
228+
<AccordionGroup>
229+
<Accordion title="Start with Quick Assessment">
230+
Always use `cu diff` and `cu log` first. Most of the time, this gives you enough information to decide next steps without the overhead of checking out or entering containers.
231+
</Accordion>
232+
233+
<Accordion title="Merge Early and Often">
234+
When an agent produces good work, merge it quickly. This creates safe checkpoints you can return to. Better to have many small merges than one large risky change.
235+
</Accordion>
236+
237+
<Accordion title="Don't Be Afraid to Delete">
238+
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.
239+
</Accordion>
240+
241+
<Accordion title="Use Specific Resume Prompts">
242+
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".
243+
</Accordion>
244+
245+
<Accordion title="Keep Your Branch Clean">
246+
Your main working branch should only contain merged, tested work. Use environments for all experimental and agent-driven development.
247+
</Accordion>
248+
</AccordionGroup>
249+
250+
## Essential Commands Reference
251+
252+
| Command | Purpose | When to Use |
253+
|---------|---------|-------------|
254+
| `cu list` | See all environments | Check status of agent work |
255+
| `cu log <env-id>` | View commit history + commands | Understand what agent did |
256+
| `cu diff <env-id>` | See code changes | Quick assessment of changes |
257+
| `cu terminal <env-id>` | Enter live container | Debug, test, hands-on exploration |
258+
| `cu checkout <env-id>` | Bring changes to local IDE | Detailed code review |
259+
| `cu merge <env-id>` | Accept work into current branch | When agent succeeded |
260+
| `cu delete <env-id>` | Discard environment | When starting over |
261+
262+
## Next Steps
263+
264+
<CardGroup cols={2}>
265+
<Card title="Try Multiple Agents" icon="users">
266+
Experiment with running multiple agents in parallel environments
267+
</Card>
268+
<Card title="Join Community" icon="discord" href="https://discord.gg/YXbtwRQv">
269+
Share your environment management strategies in #container-use
270+
</Card>
271+
</CardGroup>

0 commit comments

Comments
 (0)