Agents: git worktrees and Docker containers

Every AI agent in Agentastic works inside its own isolated environment. Isolation means that multiple agents can edit code simultaneously without stepping on each other, and you can discard an agent’s work without affecting anything else. Agentastic supports two isolation modes: git worktrees and Docker containers.

Git worktrees

What is a worktree?

A git worktree is a linked working copy of your repository. Unlike switching branches (which changes files inside a single directory), a worktree gives each branch its own complete directory on disk. Your main workspace stays untouched while an agent works in its own copy.

~/projects/
├── my-app/                    # Your main workspace
└── my-app-worktrees/
    ├── feature-auth/          # Agent 1's worktree
    ├── feature-api/           # Agent 2's worktree
    └── bugfix-login/          # Agent 3's worktree

Worktrees give you:

No file conflicts — each agent edits its own copy of your files.
True parallel work — multiple agents run simultaneously without waiting for each other.
Easy comparison — diff the agent’s branch against yours at any time.
Safe experimentation — delete a worktree if you don’t like the result, with no impact on main.

Worktree storage locations

Configure where Agentastic creates worktrees in Settings > Agents:

Location	Path pattern	Best for
Inside repo	`repo/.worktree/branch-name`	Self-contained projects
Adjacent (default)	`repo-worktrees/branch-name`	Clean separation from repo root
Global	`~/worktrees/repo/branch-name`	Centralized management across repos

Creating a worktree

From Agent Home
From Settings
From the terminal

Open Agent Home

Click the Home icon in the Navigator sidebar.

Write your prompt and set a branch name

Enter your task and choose a branch name. A random suggestion is provided.

Click Send

Agentastic creates the worktree automatically before launching the agent.

Open Settings > Agents

Use Cmd+, to open Settings, then go to the Agents section.

Click Create Agent

Choose a branch name and any additional options.

Run the standard git command directly:

git worktree add ../my-project-worktrees/feature-x -b feature-x

Switching between worktrees

Action	Shortcut
Next agent / worktree	`Cmd+Option+Down`
Previous agent / worktree	`Cmd+Option+Up`

You can also click directly on any worktree in the Agents tab of the Navigator (Cmd+4).

Removing a worktree

From Settings — open Settings > Agents, right-click the worktree, and select Remove.
From the terminal — run git worktree remove path/to/worktree.
Clean up stale references — run git worktree prune after manual deletion.

Docker containers

For maximum isolation, you can run agents inside Docker containers. Each container has its own filesystem, network stack, and pre-installed tooling, with your worktree mounted at /workspace.

Enabling containers

Install Docker Desktop

Download and install Docker Desktop. Start it and wait for it to finish initializing.

Open Agent Home

Click the Home icon in the Navigator sidebar.

Switch mode to Container

Toggle Mode from “Worktree” to “Container”.

Select a container image

Choose a pre-defined image or enter a custom one.

Launch

Click Send. Agentastic pulls the image if needed and starts the container.

Available images

Image	Description
`agentastic/soup`	All-in-one: Claude Code, Codex, Aider pre-installed
`docker/sandbox-templates:claude-code`	Official Claude Code sandbox
`paulgauthier/aider-full`	Aider AI assistant
`node:22-bookworm`	Node.js 22 environment
`python:3.12-bookworm`	Python 3.12 environment

Container mounts

Agentastic automatically mounts the following paths into every container:

Host path	Container path	Purpose
Your worktree	`/workspace`	The code the agent edits
Container home dir	`/root`	Tool state persistence across runs
`~/.gitconfig`	`/root/.gitconfig`	Git identity (optional)
`~/.ssh/`	`/root/.ssh/`	SSH keys for git operations (optional)

Network modes

Mode	Description
Bridge (default)	Full network access
Restricted	Limited to specific allowed endpoints
None	No network access

Change the network mode in Settings > Agents > Network Mode.

All built-in agents

Agentastic ships with 33 built-in agent definitions and auto-discovers them when their CLI is installed and available in your PATH.

Agent	CLI command	Install
Agentastic	`agentastic exec`	Built-in
Claude Code	`claude`	`npm install -g @anthropic-ai/claude-code`
Codex	`codex`	`npm install -g @openai/codex`
Command Code	`cmd`	`npm i -g command-code`
Cursor	`agent`	`curl https://cursor.com/install -fsSL \| bash`
Gemini	`gemini`	`npm install -g @google/gemini-cli`
Hermes Agent	`hermes`	`curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh \| bash`
Qwen Code	`qwen`	`npm install -g @qwen-code/qwen-code`
Droid	`droid`	`curl -fsSL https://app.factory.ai/cli \| sh`
Amp	`amp`	`npm install -g @sourcegraph/amp@latest`
OpenCode	`opencode`	`npm install -g opencode-ai`
GitHub Copilot	`copilot`	`npm install -g @github/copilot`
Charm	`crush`	`npm install -g @charmland/crush`
Auggie	`auggie`	`npm install -g @augmentcode/auggie`
Goose	`goose`	`curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh \| bash`
Kimi	`kimi`	`uv tool install kimi-cli`
Kilocode	`kilocode`	`npm install -g @kilocode/cli`
Kiro	`kiro-cli`	`curl -fsSL https://cli.kiro.dev/install \| bash`
Rovo Dev	`acli rovodev run`	Atlassian CLI
Cline	`cline`	`npm install -g cline`
Continue	`cn`	`npm install -g @continuedev/cli`
Codebuff	`codebuff`	`npm install -g codebuff`
Mistral Vibe	`vibe`	`curl -LsSf https://mistral.ai/vibe/install.sh \| bash`
Pi	`pi`	`npm install -g @mariozechner/pi-coding-agent`
Aider	`aider`	`pip install aider-chat`
Autohand Code	`autohand`	`curl -fsSL https://autohand.ai/install.sh \| bash`
Letta Code	`letta`	`npm install -g @letta-ai/letta-code`
OpenHands	`openhands`	`pip install openhands-ai`
Cortex Code	`cortex`	`curl -LsS https://ai.snowflake.com/static/cc-scripts/install.sh \| sh`
Junie	`junie`	`curl -fsSL https://junie.jetbrains.com/install.sh \| bash`
mini-SWE-agent	`mini`	`pip install mini-swe-agent`
OB-1	`ob1`	`curl -fsSL https://dashboard.openblocklabs.com/install \| bash`

Custom agents

Add any terminal-based AI agent in Settings > Connections. The command must accept a prompt (either as an argument or interactively).

Agent lifecycle

From launch to cleanup, every agent follows this lifecycle:

1. Create
   └── Worktree created (or container started)
   └── Setup script runs
   └── Agent CLI launched

2. Work
   └── Agent receives your prompt
   └── Agent makes file changes
   └── You monitor progress in the terminal

3. Review
   └── View diff of changes
   └── Run AI code review (optional)
   └── Test in the agent's environment

4. Complete
   └── Push branch and create a PR, or
   └── Merge directly, or
   └── Discard the changes

5. Cleanup
   └── Remove the worktree
   └── Delete the branch (optional)
   └── Container is removed (if used)

Best practices

Use descriptive branch names

Names like feature-user-auth, fix-login-bug, and refactor-api-client make it clear what each agent is working on when you have several running in parallel.

One task per agent

Keep each agent’s scope focused. Rather than asking one agent to “build the whole feature,” split it into:

“Add the database schema for users”
“Create the API endpoints”
“Build the frontend components”

Always review before merging

Before merging any agent’s work:

Open the Diff Viewer to inspect changes.
Run AI code review for automated feedback.
Test the changes in the agent’s environment.
Confirm there are no regressions.

Clean up regularly

Remove old worktrees to free disk space, keep the agent list manageable, and avoid branch name conflicts. Use Settings > Agents or run git worktree prune in the terminal.

Troubleshooting

"Branch already checked out" error

A branch can only exist in one worktree at a time. Either remove the existing worktree that has the branch checked out, or choose a different branch name for the new agent.

Container won't start

Verify Docker Desktop is running.
Check that the image exists locally: docker images.
Review container logs in Settings > Agents.

Agent not discovered in Agent Home

Agentastic discovers agents by scanning your PATH. Ensure the agent CLI is:

Installed globally (not just locally in a project).
Accessible in your PATH — confirm with which <agent-name>.
Executable (chmod +x if needed).

Get Started

Features

Guides

Reference

Help

Agents: git worktrees and Docker containers

Git worktrees

What is a worktree?

Worktree storage locations

Creating a worktree

Switching between worktrees

Removing a worktree

Docker containers

Enabling containers

Available images

Container mounts

Network modes

All built-in agents

Custom agents

Agent lifecycle

Best practices

Use descriptive branch names

One task per agent

Always review before merging

Clean up regularly

Troubleshooting

Get Started

Features

Guides

Reference

Help

Documentation Index

​Git worktrees

​What is a worktree?

​Worktree storage locations

​Creating a worktree

​Switching between worktrees

​Removing a worktree

​Docker containers

​Enabling containers

​Available images

​Container mounts

​Network modes

​All built-in agents

​Custom agents

​Agent lifecycle

​Best practices

​Use descriptive branch names

​One task per agent

​Always review before merging

​Clean up regularly

​Troubleshooting

Git worktrees

What is a worktree?

Worktree storage locations

Creating a worktree

Switching between worktrees

Removing a worktree

Docker containers

Enabling containers

Available images

Container mounts

Network modes

All built-in agents

Custom agents

Agent lifecycle

Best practices

Use descriptive branch names

One task per agent

Always review before merging

Clean up regularly

Troubleshooting