Containers

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 → Worktrees → Container 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 → Worktrees walks you through setting it up and verifying it's reachable. 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:

1. Download Docker Desktop for Mac
2. Install and launch Docker Desktop
3. 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 → Worktrees → Container 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:

1. Open Settings (Cmd+,)
2. Go to Agents
3. Click Create Agent
4. Toggle Use Container to enable container mode
5. Select a container image
6. Click Create

Agentastic will:

1. Create the git worktree
2. Pull the Docker image (if not cached locally)
3. Run your container setup script
4. Create the container with configured mounts
5. Start the container

Container Images#

Agentastic includes several pre-configured images:

Image	Description
agentastic/cloud-base	All-in-one image with Claude Code, Codex, and common agent tools
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#

1. Open Settings > Agents
2. Click Add Image in the Container Images section
3. Enter the image name (e.g., myregistry/myimage:tag)
4. Optionally specify a non-root user if the image requires it

How Containers Work#

Container Creation Flow#

Container Structure#

Inside a container:

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	Mount Git Config	Enabled
~/.ssh/	/root/.ssh/	Mount SSH Keys	Disabled
~/.oh-my-zsh/	/root/.oh-my-zsh/	Copy Shell Config	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#

How It Works#

1. Agentastic runs the script with environment variables set
2. The script outputs JSON to stdout
3. 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:

Customizing the Script#

Edit the script to add custom mounts or environment variables:

Example: Adding a custom mount for a shared cache:

Resetting to Default#

If your script has issues, reset it in Settings > Agents > Reset Setup Script.

Container Settings#

Configure container behavior in Settings > Agents.

Mount Options#

Setting	Description	Default
Mount Git Config	Share ~/.gitconfig with containers	Enabled
Mount SSH Keys	Share ~/.ssh/ with containers	Disabled
Copy Shell Config	Copy shell configs (.zshrc, .bashrc) to container home	Enabled

Network Mode#

Controls the container's network access:

Mode	Description	Use Case
Bridge	Full network access (default)	General development, API access
Restricted	Limited to specific endpoints	Security-conscious development
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 Claude
• OPENAI_API_KEY - For Codex and GPT models
• GOOGLE_API_KEY - For Google AI
• GEMINI_API_KEY - For Gemini
• GROQ_API_KEY - For Groq

Additionally, if you have ~/.config/anthropic/api_key, it's mounted into the container.

Shell Environment#

These environment variables are set automatically:

Managing Containers#

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:

1. Go to Settings > Agents
2. Select the agent
3. Click Start Container

Stopping a Container#

1. Go to Settings > Agents
2. Select the agent
3. Click Stop Container

Removing a Container#

Removing an agent with a container will:

1. Stop the container (if running)
2. Remove the container
3. Remove the git worktree
4. Optionally keep the container home directory

Terminal in Containers#

When you open a terminal in a container-backed worktree:

1. Terminal connects to the container via docker exec
2. Commands run inside the container, not on your host
3. The working directory is /workspace (your worktree)
4. Your shell configuration is available (if Copy Shell Config is enabled)

Running Commands#

Container State Persistence#

Container state is saved to:

This file maps worktree paths to their container state (ID, name, image, status, etc.).

When you reopen Agentastic:

1. Container states are loaded from this file
2. Container statuses are refreshed from Docker
3. Agents show their current container state

Troubleshooting#

Docker Not Available#

Error: "Docker is not running"

Solution:

1. Open Docker Desktop
2. Wait for Docker to fully start
3. Retry creating the container

Container Won't Start#

Error: Container status shows "exited" immediately

Solution:

1. Check the container setup script for errors
2. Verify the Docker image exists and is valid
3. Check Docker Desktop for resource limits

Setup Script Errors#

Error: "Setup script failed" or "Invalid JSON output"

Solution:

1. Open the setup script: ~/.config/agentastic/container-setup.sh
2. Run it manually to see errors:
   bashCopy

   AGENTASTIC_WORKTREE_PATH=/tmp/test \ AGENTASTIC_REPO_NAME=test \ AGENTASTIC_BRANCH=test \ ~/.config/agentastic/container-setup.sh
3. Fix any bash syntax errors
4. Ensure the output is valid JSON

Mounts Not Working#

Error: Files not appearing in container

Solution:

1. Verify the host path exists
2. Check that the path is absolute (not relative)
3. 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:

1. Enable Mount SSH Keys in Settings > Agents
2. Recreate the container (or stop and start it)
3. Inside the container, run ssh-add -l to verify keys are loaded

Network Issues in Container#

Error: Cannot connect to APIs or external services

Solution:

1. Check network mode in Settings > Agents
2. Ensure it's set to Bridge (not Restricted or None)
3. Verify Docker Desktop's network settings
4. Test connectivity: curl -I https://api.anthropic.com

Container Home Directory Issues#

Error: AI tool loses configuration between sessions

Solution:

1. Check that ~/.agentastic/container-homes/<branch>/ exists
2. Verify it's not being cleared by another process
3. Check file permissions on the directory