Containers

Run AI agents inside Docker or Apple Container β€” prerequisites, images, automatic file mounts, and the container setup script.

View as Markdown

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.

RuntimeRequirementsNotes
DockerDocker DesktopWorks on Intel and Apple Silicon; the broadest image compatibility
Apple ContainerApple Silicon Mac, no Docker DesktopApple'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:

  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 β†’ 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:

  1. Choose File > New Workspace… (Cmd+Shift+T), or click + at the bottom of the navigator sidebar
  2. Set Mode to Container β€” the picker only appears while Use containers is on in Settings > Containers and the selected runtime is reachable
  3. Select a container Image
  4. Click Create

Agent Home offers the same choice: set Environment to Container, pick an Image, and send your prompt.

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:

ImageDescription
agentastic/cloud-baseClaude Code, Codex, Amp, Gemini, OpenCode, Droid, Fx, Agentastic, and Repomix
docker/sandbox-templates:claude-codeOfficial Claude Code sandbox
paulgauthier/aider-fullAider AI coding assistant
node:22-bookwormNode.js development environment
python:3.12-bookwormPython development environment
ubuntu:24.04Minimal Ubuntu base

Adding Custom Images#

  1. Open Settings > Containers
  2. Click + under the Container Images list
  3. Enter the image name (e.g., myregistry/myimage:tag)
  4. 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 use

Container 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 PathContainer PathPurpose
<worktree-path>/workspaceYour 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 PathContainer PathPurpose
~/.agentastic/container-homes/<branch>//rootPersistent 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 PathContainer PathControlled ByDefault
~/.gitconfig/root/.gitconfigGit configurationEnabled
~/.ssh//root/.ssh/SSH keysDisabled
~/.oh-my-zsh//root/.oh-my-zsh/Shell configurationEnabled
~/.config/anthropic//root/.config/anthropic/AlwaysAuto

Why These Mounts?#

MountReason
WorktreeCentral workspace where code editing happens
Container HomeAI tools need to write state files, credentials, and configs
Git ConfigInherits your git identity (name, email) for commits
SSH KeysEnables git-over-SSH operations (disabled by default for security)
Shell ConfigPreserves your shell environment (prompt, aliases)
Anthropic ConfigAPI 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.sh

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:

VariableDescriptionExample
AGENTASTIC_WORKTREE_PATHPath to the worktree/Users/dev/repo-worktrees/feature
AGENTASTIC_REPO_NAMERepository folder namemy-project
AGENTASTIC_BRANCHBranch namefeature-auth
AGENTASTIC_MOUNT_SSH_KEYSSSH mount preferencetrue or false
AGENTASTIC_MOUNT_GIT_CONFIGGit config mount preferencetrue or false
AGENTASTIC_COPY_SHELL_CONFIGShell config copy preferencetrue or false
AGENTASTIC_NETWORK_MODENetwork mode settingbridge, restricted, or none

Output Format#

The script must output valid JSON:

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:

bash
# Open in your editor open ~/.config/agentastic/container-setup.sh

Example: Adding a custom mount for a shared cache:

bash
# 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#

SettingDescriptionDefault
Shell configurationCopy shell configs (.zshrc, .bashrc) to container homeEnabled
Git configurationShare ~/.gitconfig with containersEnabled
SSH keysShare ~/.ssh/ with containersDisabled

Network Mode#

The Network access picker controls the container's network access:

ModeDescriptionUse Case
Full access (bridge)Full network access (default)General development, API access
API only (restricted)Limited to specific endpointsSecurity-conscious development
None (none)No network accessOffline 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
  • MISTRAL_API_KEY, DEEPSEEK_API_KEY, and XAI_API_KEY - For those model providers
  • OPENROUTER_API_KEY - For OpenRouter and OpenCode
  • FACTORY_API_KEY - For Droid
  • AI_GATEWAY_API_KEY and VERCEL_OIDC_TOKEN - For Fx
  • AGENTASTIC_API_KEY, AGENTASTIC_ACCESS_TOKEN, and AGENTASTIC_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:

bash
TERM=xterm-256color LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 HOME=/root SHELL=/bin/bash USER=root

Managing 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#

StateDescription
CreatedContainer exists but hasn't started
RunningContainer is active and ready
PausedContainer is suspended
ExitedContainer has stopped
DeadContainer 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:

  1. Stop the container (if running)
  2. Remove the container
  3. Remove the git worktree
  4. Leave the container home directory in place under ~/.agentastic/container-homes/

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 Shell configuration is on)

Running Commands#

bash
# 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 /tmp and 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 artifact works inside the container. Agentastic puts its own dev first on the agent's PATH, at ~/.agentastic/bin/dev in the container home, and that dev hands 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.json

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:
    bash
    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. Turn on SSH keys in Settings > Containers
  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 access in Settings > Containers
  2. Ensure it's set to Full access (not API only 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