Containers
Run AI agents inside Docker or Apple Container β prerequisites, images, automatic file mounts, and the container setup script.
On this page
- Overview
- Container Runtimes
- Prerequisites
- Docker
- Apple Container
- Creating a Container
- Container Images
- Adding Custom Images
- How Containers Work
- Container Creation Flow
- Container Structure
- Automatic File Mounts
- Worktree Mount (Read-Write)
- Container Home Directory (Read-Write)
- Configuration Mounts (Read-Only)
- Why These Mounts?
- Container Setup Script
- Default Location
- How It Works
- Environment Variables
- Output Format
- Customizing the Script
- Resetting to Default
- Container Settings
- Shared from Your Mac
- Network Mode
- Setup Script Path
- Environment Variables
- API Keys
- Shell Environment
- Managing Containers
- From Agent Home
- Container States
- Starting a Container
- Stopping a Container
- Removing a Container
- Terminal in Containers
- Running Commands
- Attachments, Skills, Plugins, and Artifacts
- Container State Persistence
- Troubleshooting
- Docker Not Available
- Container Won't Start
- Setup Script Errors
- Mounts Not Working
- SSH Keys Not Available
- Network Issues in Container
- Container Home Directory Issues
Overview#
Agentastic can run AI coding agents inside local containers instead of directly on your host machine. Each worktree can optionally have an associated container that provides:
- Isolation - Agents run in a sandboxed environment
- Reproducibility - Consistent environments across machines
- Security - Limited access to host filesystem and network
- Flexibility - Pre-configured images with tools installed
Container Runtimes#
Agentastic supports two local container runtimes. Choose which one to use under Settings β Containers β Runtime β the same worktrees, mounts, and terminals work with either.
| Runtime | Requirements | Notes |
|---|---|---|
| Docker | Docker Desktop | Works on Intel and Apple Silicon; the broadest image compatibility |
| Apple Container | Apple Silicon Mac, no Docker Desktop | Apple's native container tool β lightweight, runs Linux containers in fast per-container VMs |
The first time you select a runtime, Settings β Containers walks you through setting it up and verifying it's reachable β the page shows whether the selected runtime is available, and its Setupβ¦ button installs or starts it. Container sessions are backed by stable tmux sessions for both runtimes, so your agent's terminal reconnects after an app restart.
Prerequisites#
Docker#
Docker Desktop must be installed and running on your Mac:
- Download Docker Desktop for Mac
- Install and launch Docker Desktop
- Verify Docker is running (whale icon in menu bar)
Agentastic communicates directly with Docker via the Unix socket at /var/run/docker.sock.
Apple Container#
Apple Container runs on Apple Silicon and does not require Docker Desktop. Install Apple's container tool, then select Apple Container under Settings β Containers β Runtime and run the built-in setup to start the runtime. Image pulls, container lifecycle, exec, and terminal launch all work the same as Docker.
Creating a Container#
When creating a new worktree, you can enable container mode:
- Choose File > New Workspace⦠(Cmd+Shift+T), or click + at the bottom of the navigator sidebar
- Set Mode to Container β the picker only appears while Use containers is on in Settings > Containers and the selected runtime is reachable
- Select a container Image
- Click Create
Agent Home offers the same choice: set Environment to Container, pick an Image, and send your prompt.
Agentastic will:
- Create the git worktree
- Pull the Docker image (if not cached locally)
- Run your container setup script
- Create the container with configured mounts
- Start the container
Container Images#
Agentastic includes several pre-configured images:
| Image | Description |
|---|---|
agentastic/cloud-base | Claude Code, Codex, Amp, Gemini, OpenCode, Droid, Fx, Agentastic, and Repomix |
docker/sandbox-templates:claude-code | Official Claude Code sandbox |
paulgauthier/aider-full | Aider AI coding assistant |
node:22-bookworm | Node.js development environment |
python:3.12-bookworm | Python development environment |
ubuntu:24.04 | Minimal Ubuntu base |
Adding Custom Images#
- Open Settings > Containers
- Click + under the Container Images list
- Enter the image name (e.g.,
myregistry/myimage:tag) - Optionally specify a non-root user if the image requires it
The agent commands are resolved when the image is built. Package selectors
such as @latest fetch the newest release during that build; an already-built
image or running container does not update itself. Agentastic uses a versioned
cloud-base tag so providers cannot silently reuse a cached mutable tag. A
tool update therefore requires rebuilding and publishing the image, bumping
the image tag in Agentastic, and creating or pulling a new container.
Maintainer releases use two phases: CI first publishes and verifies a new
immutable candidate for both amd64 and arm64, then a separate promotion
change updates the app default. This prevents a released app from selecting an
image tag that has not reached the public registry yet.
How Containers Work#
Container Creation Flow#
User Creates Worktree with Container
|
v
1. Create git worktree on host
|
v
2. Pull Docker image (if needed)
|
v
3. Run container-setup.sh on HOST
- Outputs JSON configuration
- Defines mounts, env vars, network
|
v
4. Create container home directory
~/.agentastic/container-homes/<branch>/
|
v
5. Copy shell configs to container home
(.zshrc, .bashrc, etc.)
|
v
6. Create Docker container with:
- Worktree mounted at /workspace
- Home directory mounted at /root
- Config files mounted read-only
|
v
7. Container ready for useContainer Structure#
Inside a container:
/
βββ workspace/ # Your worktree (read-write)
βββ root/ # Container home directory (read-write)
β βββ .zshrc # Copied from host
β βββ .bashrc # Copied from host
β βββ .claude/ # AI tool state files
βββ root/.gitconfig # Mounted read-only from host
βββ root/.ssh/ # Mounted read-only (if enabled)
βββ root/.config/
βββ anthropic/ # API keys (read-only)Automatic File Mounts#
Agentastic automatically mounts several files and directories into containers. Understanding these mounts helps you configure your environment.
Worktree Mount (Read-Write)#
| Host Path | Container Path | Purpose |
|---|---|---|
<worktree-path> | /workspace | Your code - this is where agents work |
The worktree is always mounted at /workspace. This is the working directory for all AI agents.
Container Home Directory (Read-Write)#
| Host Path | Container Path | Purpose |
|---|---|---|
~/.agentastic/container-homes/<branch>/ | /root | Persistent home for the container |
Each container gets its own home directory on the host. This allows:
- AI tools (Claude Code, Codex, etc.) to write their state and config files
- Shell history to persist across container restarts
- Tool credentials to be saved
Configuration Mounts (Read-Only)#
These mounts share your host configuration with the container while preventing modifications:
| Host Path | Container Path | Controlled By | Default |
|---|---|---|---|
~/.gitconfig | /root/.gitconfig | Git configuration | Enabled |
~/.ssh/ | /root/.ssh/ | SSH keys | Disabled |
~/.oh-my-zsh/ | /root/.oh-my-zsh/ | Shell configuration | Enabled |
~/.config/anthropic/ | /root/.config/anthropic/ | Always | Auto |
Why These Mounts?#
| Mount | Reason |
|---|---|
| Worktree | Central workspace where code editing happens |
| Container Home | AI tools need to write state files, credentials, and configs |
| Git Config | Inherits your git identity (name, email) for commits |
| SSH Keys | Enables git-over-SSH operations (disabled by default for security) |
| Shell Config | Preserves your shell environment (prompt, aliases) |
| Anthropic Config | API key file for Claude authentication |
Container Setup Script#
The setup script is a user-editable bash script that runs on your host machine before container creation. It outputs JSON configuration that defines container mounts, environment variables, and settings.
Default Location#
~/.config/agentastic/container-setup.shHow It Works#
- Agentastic runs the script with environment variables set
- The script outputs JSON to stdout
- Agentastic parses the JSON and configures the container
Environment Variables#
The setup script receives these environment variables:
| Variable | Description | Example |
|---|---|---|
AGENTASTIC_WORKTREE_PATH | Path to the worktree | /Users/dev/repo-worktrees/feature |
AGENTASTIC_REPO_NAME | Repository folder name | my-project |
AGENTASTIC_BRANCH | Branch name | feature-auth |
AGENTASTIC_MOUNT_SSH_KEYS | SSH mount preference | true or false |
AGENTASTIC_MOUNT_GIT_CONFIG | Git config mount preference | true or false |
AGENTASTIC_COPY_SHELL_CONFIG | Shell config copy preference | true or false |
AGENTASTIC_NETWORK_MODE | Network mode setting | bridge, restricted, or none |
Output Format#
The script must output valid JSON:
{
"mounts": [
{"host": "/path/on/host", "container": "/path/in/container", "readonly": true}
],
"env": {
"ANTHROPIC_API_KEY": "sk-...",
"TERM": "xterm-256color"
},
"network": "bridge",
"extraArgs": [],
"workdir": "/workspace",
"shell": "/bin/bash"
}Customizing the Script#
Edit the script to add custom mounts or environment variables:
# Open in your editor
open ~/.config/agentastic/container-setup.shExample: Adding a custom mount for a shared cache:
# Add to the MOUNTS array in the script
MOUNTS+='{"host": "'"$HOME"'/.npm", "container": "/root/.npm", "readonly": false},'Resetting to Default#
If your script has issues, reset it with the Reset button next to Setup script in Settings > Containers.
Container Settings#
Configure container behavior in Settings > Containers.
Shared from Your Mac#
| Setting | Description | Default |
|---|---|---|
| Shell configuration | Copy shell configs (.zshrc, .bashrc) to container home | Enabled |
| Git configuration | Share ~/.gitconfig with containers | Enabled |
| SSH keys | Share ~/.ssh/ with containers | Disabled |
Network Mode#
The Network access picker controls the container's network access:
| Mode | Description | Use Case |
|---|---|---|
Full access (bridge) | Full network access (default) | General development, API access |
API only (restricted) | Limited to specific endpoints | Security-conscious development |
None (none) | No network access | Offline work, maximum isolation |
Setup Script Path#
Optionally specify a custom path for the container setup script. Leave empty to use the default (~/.config/agentastic/container-setup.sh).
Environment Variables#
API Keys#
API keys from your host environment are automatically passed to containers:
ANTHROPIC_API_KEY- For ClaudeOPENAI_API_KEY- For Codex and GPT modelsGOOGLE_API_KEY- For Google AIGEMINI_API_KEY- For GeminiGROQ_API_KEY- For GroqMISTRAL_API_KEY,DEEPSEEK_API_KEY, andXAI_API_KEY- For those model providersOPENROUTER_API_KEY- For OpenRouter and OpenCodeFACTORY_API_KEY- For DroidAI_GATEWAY_API_KEYandVERCEL_OIDC_TOKEN- For FxAGENTASTIC_API_KEY,AGENTASTIC_ACCESS_TOKEN, andAGENTASTIC_OAUTH_ACCESS_TOKEN- For Agentastic
Additionally, if you have ~/.config/anthropic/api_key, it's mounted into the container.
Agentastic also copies the allowlisted login files for Claude Code, Codex, Droid, Fx, OpenCode, and Agentastic into the writable container home. For credentials stored in macOS Keychain, it asks for access and materializes the equivalent Linux file with private permissions. Agent histories, logs, caches, and worktrees are not copied.
Shell Environment#
These environment variables are set automatically:
TERM=xterm-256color
LANG=en_US.UTF-8
LC_ALL=en_US.UTF-8
HOME=/root
SHELL=/bin/bash
USER=rootManaging Containers#
From Agent Home#
A container agent you launch from Agent Home gets a status row under the prompt, marked with a box icon. The row has the same controls as a cloud agent's:
- Sleep Container (moon icon) stops the container and keeps its files. Wake Container (power icon) starts it again.
- The terminal icon opens a terminal inside the running container.
- Local Bridge opens the worktree's folder, or a terminal, on your Mac. The container works in that folder directly, so there is nothing to sync.
- β deletes the worktree and its container after asking, like Delete Workspace in the sidebar.
Right-click the row to sleep, wake, open a terminal, or delete. While the row is on screen, Agentastic checks the container every 10 seconds, so a container stopped outside Agentastic shows as asleep. Agentastic doesn't keep these rows after you quit it.
Container States#
| State | Description |
|---|---|
| Created | Container exists but hasn't started |
| Running | Container is active and ready |
| Paused | Container is suspended |
| Exited | Container has stopped |
| Dead | Container failed to stop properly |
Starting a Container#
If a container exists but isn't running, Agentastic starts it on demand: opening a terminal in the container-backed worktree (right-click it in the navigator sidebar and choose New Terminal) or launching an agent there starts the container before connecting. A stopped container agent's row in Agent Home also has a Wake Container button.
Stopping a Container#
A container keeps running until you stop it or delete its worktree, which stops and removes it. To stop the container of an agent you launched from Agent Home, click Sleep Container on its status row. That ends everything running inside, including the agent, and keeps the files. For any other container, use your runtime directly (Docker Desktop, docker stop, or container stop); containers are named agentastic-<branch>, lowercased with / replaced by -. The next terminal or agent launch in that worktree starts it again.
Removing a Container#
Deleting a container-backed worktree (right-click it in the navigator sidebar and choose Delete Workspace, or click β on its Agent Home status row) will:
- Stop the container (if running)
- Remove the container
- Remove the git worktree
- Leave the container home directory in place under
~/.agentastic/container-homes/
Terminal in Containers#
When you open a terminal in a container-backed worktree:
- Terminal connects to the container via
docker exec - Commands run inside the container, not on your host
- The working directory is
/workspace(your worktree) - Your shell configuration is available (if Shell configuration is on)
Running Commands#
# You're now inside the container
pwd
# /workspace
# Run your AI agent
claude
# Or Codex
codex "implement feature X"Attachments, Skills, Plugins, and Artifacts#
An agent you start in a container from Agent Home or Chat, with Docker or Apple Container, gets the same extras as one on your Mac:
- Attachments. Images and files you attach, at launch or on any later Chat turn, are copied into a private folder in the container's
/tmpand removed when the agent or the turn finishes. Nothing is written into your worktree. - Skills. The skills you attach are copied into the container home, under
~/.agentastic/skill-snapshots, where the agent reads them. - Plugins. MCP servers from your plugins are configured in the container home. Desktop plugins marked
localOnly, such as Paper, are left out, because they need apps on your Mac. - Artifacts.
dev artifactworks inside the container. Agentastic puts its owndevfirst on the agent'sPATH, at~/.agentastic/bin/devin the container home, and thatdevhands each command to the app through~/.agentastic/dev-bridge/. Agents can publish, render, pull, share, and comment on artifacts as usual. They can publish only files inside the container's worktree, and can't delete artifacts.
Other dev commands, such as dev browser or dev notify, aren't available inside a container. dev artifact needs Agentastic running on your Mac. If Agentastic restarted after the agent started, start the agent again from Agentastic so its dev can reach the app.
Container State Persistence#
Container state is saved to:
~/.agentastic/application-support/Agentastic.dev/container-states.jsonThis file maps worktree paths to their container state (ID, name, image, status, etc.).
When you reopen Agentastic:
- Container states are loaded from this file
- Container statuses are refreshed from Docker
- Agents show their current container state
Troubleshooting#
Docker Not Available#
Error: "Docker is not running"
Solution:
- Open Docker Desktop
- Wait for Docker to fully start
- Retry creating the container
Container Won't Start#
Error: Container status shows "exited" immediately
Solution:
- Check the container setup script for errors
- Verify the Docker image exists and is valid
- Check Docker Desktop for resource limits
Setup Script Errors#
Error: "Setup script failed" or "Invalid JSON output"
Solution:
- Open the setup script:
~/.config/agentastic/container-setup.sh - Run it manually to see errors:
bash
AGENTASTIC_WORKTREE_PATH=/tmp/test \ AGENTASTIC_REPO_NAME=test \ AGENTASTIC_BRANCH=test \ ~/.config/agentastic/container-setup.sh - Fix any bash syntax errors
- Ensure the output is valid JSON
Mounts Not Working#
Error: Files not appearing in container
Solution:
- Verify the host path exists
- Check that the path is absolute (not relative)
- Ensure Docker has permission to access the directory (check Docker Desktop > Settings > Resources > File Sharing)
SSH Keys Not Available#
Error: git push fails with authentication error
Solution:
- Turn on SSH keys in Settings > Containers
- Recreate the container (or stop and start it)
- Inside the container, run
ssh-add -lto verify keys are loaded
Network Issues in Container#
Error: Cannot connect to APIs or external services
Solution:
- Check Network access in Settings > Containers
- Ensure it's set to Full access (not API only or None)
- Verify Docker Desktop's network settings
- Test connectivity:
curl -I https://api.anthropic.com
Container Home Directory Issues#
Error: AI tool loses configuration between sessions
Solution:
- Check that
~/.agentastic/container-homes/<branch>/exists - Verify it's not being cleared by another process
- Check file permissions on the directory