- Default Configuration: Your project’s baseline environment that all agents start from
- 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
Set Default Configuration
Configure your project’s baseline environment that all agents will start from
Agent Starts with Defaults
When an agent creates a new environment, it begins with your default configuration
Agent Adapts as Needed
During work, the agent may modify its environment configuration - adding tools, changing base images, or setting variables
View Agent Changes
Use
container-use config show <env> to see what configuration changes the agent madeDefault 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: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
Import Agent Changes
When agents make useful changes, import them as your new defaults:Configuration Commands
Base Image
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:Install Commands
Run after copying code:Environment Variables
Secrets
Configure secure access to API keys and credentials. See the complete secrets guide for all secret types and examples.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:Next Steps
Environment Workflow
Learn how to work with the environments agents create
Agent Integrations
Set up your coding agent to work with Container Use