Run AI CLI Tools in Docker or Podman Safely (2026 Guide)

AI coding agents can write files, run shell commands, and read anything your user account can reach. This guide shows you how to run AI CLI tools in Docker or Podman inside a safe, isolated environment, so a hallucinated rm -rf or a bad dependency install can’t touch your machine. You’ll build one container image that hosts Claude Code, Amp, Factory.ai, Gemini CLI, OpenCode, and GitHub Copilot CLI, each with its own configs, API keys, and project mounts.

The honest version of the pitch: a container is isolation, not a virtual machine. It shares your kernel. If you mount your SSH keys or the Docker socket into it, you’ve handed the agent your host anyway. Everything in this guide is built around not doing that.

If you want the same idea but with the agent living on a server instead of your laptop, our NanoClaw deploy guide covers a container-isolated Claude agent on a VPS.

Why run AI CLI tools in Docker or Podman? (isolation and sandboxing)

Sandboxing AI coding agents with containers buys you six things:

What containers do not give you:

• Kernel isolation. A container escape is a host compromise. If you need a real security boundary, use a VM (this is the same reason we run untrusted code in VMs, not containers).
• Protection from mounted data. The agent can delete anything inside the directories you mount. Mount a project directory, not a directory of projects you can’t afford to lose.
• Protection from the network. The container has outbound internet unless you configure otherwise. An agent can still exfiltrate whatever it can read.

Prerequisites: Docker Desktop or Podman Desktop

Pick one container engine. Docker if you already know it, Podman if you’re on Fedora or you want rootless by default. Everything else in this guide works the same way.

docker --version
docker compose version

Docker version 29.7.2, build ...
Docker Compose version v2.x.x

# Fedora/RHEL/CentOS
sudo dnf install podman podman-compose

# Ubuntu/Debian
sudo apt install podman podman-compose

# macOS (via Homebrew)
brew install podman podman-compose

podman machine init
podman machine start

podman --version
podman compose version
podman info --format '{{.Host.Security.Rootless}}'

Container architecture overview: the Python and Node base image

One image, both runtimes. Almost every AI CLI tool is a Node package or a shell script that also wants Python for tooling, and rebuilding that stack per tool is wasted time.

We use nikolaik/python-nodejs, which ships:

Why Node 26 instead of Node 25? Node 25 was an odd-numbered, non-LTS line and it reached end of life in mid-2026. If you built this container from a 2025 guide, your base image is on an EOL runtime with no security patches. That’s the whole reason to rebuild.

The UID 1000 detail matters more than it sounds. Because pn is UID 1000, files it creates inside a bind-mounted ~/websites land owned by UID 1000 on your host, which is your normal Linux user in most distros. If your host user is not 1000, read the permission section in troubleshooting.

Step 1: create the project structure

mkdir -p ~/docker-ai-tools ~/dev-home ~/websites
cd ~/docker-ai-tools

mkdir -p ~/podman-ai-tools ~/dev-home ~/websites
cd ~/podman-ai-tools

What each directory is for:

• ~/docker-ai-tools or ~/podman-ai-tools: the container config files (Dockerfile, compose file, .env)
• ~/dev-home: the container user’s home directory, bind mounted. Holds CLI configs, auth state, and installed tools. Survives container rebuilds.
• ~/websites: your actual projects, bind mounted into the container. This is the only thing the agent should be able to touch.

sudo chown -R 1000:1000 ~/dev-home ~/websites

Step 2: create the Containerfile/Dockerfile

# Dockerfile
# Base image with Node.js 26, Python 3.14, and package managers
FROM nikolaik/python-nodejs:python3.14-nodejs26-bookworm

SHELL ["/bin/bash", "-c"]

# The image already has a non-root user "pn" (UID 1000)
USER root

# Install system dependencies first
RUN apt-get update && apt-get install -y --no-install-recommends \
    git \
    jq \
    curl \
    vim \
    nano \
    htop \
    tree \
    ripgrep \
    rsync \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Starship prompt system-wide
# This works even when /home/pn is bind-mounted from the host
RUN curl -sS https://starship.rs/install.sh | sh -s -- -y \
 && mkdir -p /opt/skeleton/.config \
 && starship preset catppuccin-powerline -o /opt/skeleton/.config/starship.toml

# Minimal Bash configuration with Starship
RUN cat > /opt/skeleton/.bashrc <<'BRC'
# Bash initialized for pn user
# Enable Node Corepack and Yarn
corepack enable >/dev/null 2>&1 || true
corepack prepare yarn@stable --activate >/dev/null 2>&1 || true

# Quality of life alias
alias python=python3

# Initialize Starship prompt
if command -v starship >/dev/null 2>&1; then
  eval "$(starship init bash)"
fi
BRC

# Entrypoint script to seed dotfiles on first run
RUN cat > /usr/local/bin/boot.sh <<'SH'
#!/usr/bin/env bash
set -euo pipefail

# Seed ~/.bashrc if missing (e.g. empty bind-mounted /home/pn)
if [ ! -f "/home/pn/.bashrc" ]; then
  cp /opt/skeleton/.bashrc /home/pn/.bashrc
fi

# Seed Starship config if missing
mkdir -p /home/pn/.config
if [ ! -f "/home/pn/.config/starship.toml" ]; then
  cp /opt/skeleton/.config/starship.toml /home/pn/.config/starship.toml
fi

# Default to interactive bash if no command was provided
if [ $# -eq 0 ]; then
  set -- bash
fi
exec "$@"
SH
RUN chmod +x /usr/local/bin/boot.sh

# Switch back to the non-root user
USER pn
WORKDIR /home/pn/app

ENTRYPOINT ["/usr/local/bin/boot.sh"]
CMD ["bash"]

# Containerfile
# Base image with Node.js 26, Python 3.14, and package managers
FROM nikolaik/python-nodejs:python3.14-nodejs26-bookworm

SHELL ["/bin/bash", "-c"]

# The image already has a non-root user "pn" (UID 1000)
USER root

# Install system dependencies first
RUN apt-get update && apt-get install -y --no-install-recommends \
    git \
    jq \
    curl \
    vim \
    nano \
    htop \
    tree \
    ripgrep \
    rsync \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Starship prompt system-wide
# This works even when /home/pn is bind-mounted from the host
RUN curl -sS https://starship.rs/install.sh | sh -s -- -y \
 && mkdir -p /opt/skeleton/.config \
 && starship preset catppuccin-powerline -o /opt/skeleton/.config/starship.toml

# Minimal Bash configuration with Starship
RUN cat > /opt/skeleton/.bashrc <<'BRC'
# Bash initialized for pn user
# Enable Node Corepack and Yarn
corepack enable >/dev/null 2>&1 || true
corepack prepare yarn@stable --activate >/dev/null 2>&1 || true

# Quality of life alias
alias python=python3

# Initialize Starship prompt
if command -v starship >/dev/null 2>&1; then
  eval "$(starship init bash)"
fi
BRC

# Entrypoint script to seed dotfiles on first run
RUN cat > /usr/local/bin/boot.sh <<'SH'
#!/usr/bin/env bash
set -euo pipefail

# Seed ~/.bashrc if missing (e.g. empty bind-mounted /home/pn)
if [ ! -f "/home/pn/.bashrc" ]; then
  cp /opt/skeleton/.bashrc /home/pn/.bashrc
fi

# Seed Starship config if missing
mkdir -p /home/pn/.config
if [ ! -f "/home/pn/.config/starship.toml" ]; then
  cp /opt/skeleton/.config/starship.toml /home/pn/.config/starship.toml
fi

# Default to interactive bash if no command was provided
if [ $# -eq 0 ]; then
  set -- bash
fi
exec "$@"
SH
RUN chmod +x /usr/local/bin/boot.sh

# Switch back to the non-root user
USER pn
WORKDIR /home/pn/app

ENTRYPOINT ["/usr/local/bin/boot.sh"]
CMD ["bash"]

Running as a non-root user with USER pn

The USER pn line at the end is the security-relevant one. Everything installed at runtime, every file the agent creates, and every process the agent spawns runs as UID 1000 inside the container, not as root. The install steps still use USER root temporarily because you need root to run apt-get, but the final image and the running container are non-root.

That matters for sandboxing because most container escapes rely on root inside the container plus either a kernel bug or a misconfiguration (a mounted socket, a privileged flag, a --cap-add). Running as UID 1000 removes the easy path.

If you want the deeper walkthrough of what non-root users inside containers do and don’t protect you from, we have a separate guide on running a container as a non-root user.

Two exceptions worth knowing:

• Ports below 1024. Non-root can’t bind them inside the container. The dev servers you’d run next to an agent (3000, 4321, 5173, 8080) are all above 1024, so this rarely bites.
• System package installs. apt-get install needs root. That’s why the “install a missing command” section below uses docker exec --user root.

What this Containerfile does

Step 3: create the compose configuration

services:
  ai-tools:
    build:
      context: .
      dockerfile: Dockerfile
    image: ai-tools:latest
    container_name: ai-tools
    restart: unless-stopped
    tty: true
    stdin_open: true
    environment:
      - TZ=Europe/Bucharest      # Change to your timezone
    env_file:
      - .env                     # API keys - do not commit this file
    volumes:
      - ${HOME}/dev-home:/home/pn
      - ${HOME}/websites:/home/pn/app/websites
    security_opt:
      - no-new-privileges:true
    # Uncomment only if a tool needs an OAuth callback or a local server
    # ports:
    #   - "127.0.0.1:3000:3000"  # bind to localhost, not 0.0.0.0

services:
  ai-tools:
    build:
      context: .
      dockerfile: Containerfile
    image: ai-tools:latest
    container_name: ai-tools
    restart: unless-stopped
    tty: true
    stdin_open: true
    environment:
      - TZ=Europe/Bucharest      # Change to your timezone
    env_file:
      - .env                     # API keys - do not commit this file
    volumes:
      - ${HOME}/dev-home:/home/pn:z
      - ${HOME}/websites:/home/pn/app/websites:z
    security_opt:
      - no-new-privileges:true
    # Uncomment only if a tool needs an OAuth callback or a local server
    # ports:
    #   - "127.0.0.1:3000:3000"  # bind to localhost, not 0.0.0.0

Validate the file before you build. Compose silently ignores typos in some fields:

docker compose config
# or: podman compose config

If the merged YAML prints and the ai-tools service has both volumes, you’re good. If a volume is missing from the output, you have an indentation problem.

When to expose ports for OAuth callbacks

Most AI CLI tools authenticate either with an API key in an environment variable or with a device-code flow (print a URL, paste a code). Neither needs a port.

Add a port only when a tool opens a local HTTP listener for an OAuth redirect on localhost:

Bind the published port to 127.0.0.1, not to all interfaces. "3000:3000" publishes on every interface the host has, which on a VPS means the internet. "127.0.0.1:3000:3000" doesn’t.

Step 4: build and start the container

cd ~/docker-ai-tools

# Build the image
docker compose build

# Start the container detached
docker compose up -d

# Enter the container
docker exec -it ai-tools bash

docker compose down

cd ~/podman-ai-tools

# Ensure the Podman machine is running (macOS/Windows only)
podman machine start

# Build the image
podman compose build

# Start the container detached
podman compose up -d

# Enter the container
podman exec -it ai-tools bash

podman compose down

Verify it’s actually running:

docker compose ps

NAME       IMAGE            COMMAND                  SERVICE   STATUS
ai-tools   ai-tools:latest  "/usr/local/bin/boot.…"  ai-tools  Up 12 seconds

Up is what you want. Restarting in a loop means the entrypoint is crashing - see troubleshooting.

The first build takes a few minutes (it downloads a ~580 MB base image). Subsequent builds are cached. Use --no-cache only when you actually changed the base image; it throws away every layer and re-downloads everything.

Step 5: verify the container environment

Inside the container, check that the versions are what the tag promised:

# You should not be root
whoami
id -u
# Expected: pn
# Expected: 1000

# Node and package managers
node -v            # v26.8.2
npm -v             # 11.x
yarn -v            # 4.x (via Corepack)

# Python and package managers
python3 -V         # Python 3.14.7
pip --version      # 25.x
poetry --version
uv --version

# Shell tooling
which starship
# Expected: /usr/local/bin/starship

# Mounts
ls -la ~/app/websites
touch ~/app/websites/.mount-test && ls -la ~/app/websites/.mount-test

That touch is the test that matters. If it fails, the mount is wrong and you’d only find out later, when the agent writes a file into a container-local directory that vanishes on the next docker compose down.

ls -la ~/websites/.mount-test

rm ~/websites/.mount-test

Step 6: install AI CLI tools (Claude Code, Amp, Gemini CLI, OpenCode)

Not sure which agent to pick? We compared the best AI coding tools and agents in 2026. Install more than one - they’re 10-100 MB each and there’s no downside to having Claude Code, Amp, and OpenCode side by side.

From here on, everything runs inside the container, so the commands are identical for Docker and Podman. Enter once:

docker exec -it ai-tools bash   # or: podman exec -it ai-tools bash

# Docker
docker exec -it --user root ai-tools bash
# Podman
podman exec -it --user root ai-tools bash

Install Claude Code in the container

The native installer is the one to use. It doesn’t care about your Node version and it self-updates.

# Native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash

# Verify
claude --version

If your base image Node setup fights the native binary, the npm route still works:

npm install -g @anthropic-ai/claude-code
claude --version

Where things land: the native installer puts the binary in ~/.local/bin by default, so it survives a container rebuild only because ~/.local lives inside the bind-mounted /home/pn. That’s the reason the home mount exists.

Install Amp and Factory.ai

# Amp
curl -fsSL https://ampcode.com/install.sh | bash

# Factory.ai CLI
curl -fsSL https://app.factory.ai/cli | sh

# Verify
amp --version
droid --version

Amp dropped a free tier during 2025, so check current pricing before you build a workflow around it. Background on how it works in the editor: Amp Code AI coding agent.

Factory’s Droid CLI is the other one worth installing here, especially if you want to point it at your own model endpoints instead of a bundled subscription:

You can configure Factory to hit your own providers (including a local Ollama) - the config file example is further down.

Install Gemini CLI, OpenCode and GitHub Copilot CLI

# Gemini CLI
npm install -g @google/gemini-cli

# GitHub Copilot CLI (needs a Copilot subscription)
npm install -g @github/copilot

# OpenCode
curl -fsSL https://opencode.ai/install | bash

# Verify all three
gemini --version
copilot --version
opencode --version

Two notes from the 2025 version of this guide:

• GitHub Copilot CLI moved packages. The old @githubnext/github-copilot-cli beta package is dead. The current one is @github/copilot. If you get a deprecation warning, you’re on the old package.
• OpenCode installs to ~/.opencode/bin in recent versions, not /usr/local/bin. If opencode: command not found after a clean install, add ~/.opencode/bin to your PATH in the seeded .bashrc.

Want to skip managing six API keys? The OpenCode Go subscription bundles a pile of models behind one key, which is the cheapest way to run a containerized agent without a wallet full of tokens:

Full setup, including Zen sign-in and provider config: OpenCode setup guide. For Copilot specifics (models, plan limits, the $10 tier), see our GitHub Copilot Pro CLI setup.

And if you’d rather route Claude Code, Codex, and Gemini CLI through a single endpoint with one key and per-model billing, that’s what an aggregator is for:

Authenticate with CLI tools (OAuth and API keys)

# Device-code or browser flows
claude          # then /login inside the session
amp login
droid           # then /login inside the session
opencode auth login
copilot         # then /login
gemini          # follow the auth prompt

ports:
  - "127.0.0.1:3000:3000"

Working with projects

~/websites on your host is /home/pn/app/websites inside the container. That means:

Example workflow: host edits, container runs

# On the host
cd ~/websites
mkdir my-new-project && cd my-new-project
git init

# Inside the container
cd ~/app/websites/my-new-project
amp "Create a Next.js app with TypeScript"

One footgun: don’t run the same package manager on both sides of the mount. If the host runs npm install and the container runs pnpm install in the same directory, they fight over node_modules. Pick one side to be authoritative - inside the container is the sane choice, since the runtime versions are pinned there.

Configuring AI tools inside the container

Configs persist because ~/dev-home maps to /home/pn. Edit them from either side; a nano session inside the container and code ~/dev-home/... on the host are touching the same file.

Example: Factory.ai custom models

# Inside the container
nano ~/.factory/config.json

{
  "custom_models": [
    {
      "model_display_name": "Claude Sonnet 4.5",
      "model": "claude-sonnet-4-5-20250929",
      "base_url": "https://api.anthropic.com",
      "api_key": "your-api-key-here",
      "provider": "anthropic",
      "max_tokens": 8192
    },
    {
      "model_display_name": "GPT-5 Codex",
      "model": "gpt-5-codex",
      "base_url": "https://api.openai.com/v1",
      "api_key": "your-openai-key-here",
      "provider": "openai",
      "max_tokens": 8192
    },
    {
      "model_display_name": "Qwen 3 (Local Ollama)",
      "model": "qwen3:14b",
      "base_url": "http://ollama:11434/v1",
      "api_key": "ollama",
      "provider": "generic-chat-completion-api",
      "max_tokens": 4096
    }
  ]
}

Note the base_url for Ollama: http://ollama:11434/v1, not http://localhost:11434/v1. Inside a container, localhost is the container itself. If you run Ollama as a separate compose service (recommended, see below), the service name is the hostname.

Accessing host files from the container

# Inside the container
ls -la ~/.factory/     # Factory.ai configs
ls -la ~/.amp/         # Amp configs
ls -la ~/.config/      # everything else
cat ~/.bashrc          # shell config

Edit the same files from the host:

# On the host
code ~/dev-home/.factory/config.json
code ~/dev-home/.bashrc
code ~/dev-home/.config/starship.toml

Changes take effect on the next shell inside the container (or immediately, for config files tools re-read per request).

sudo chown 1000:1000 ~/dev-home/.factory/config.json

Advanced configuration

Running local AI models with Ollama

The 2025 version of this guide told you to install Ollama inside the agent container. Don’t. It bloats the agent image, and the model weights end up in a volume that gets wiped when you rebuild. Run Ollama as its own service and let the agent talk to it over the compose network.

Add a second service to your compose file:

services:
  ai-tools:
    # ... your existing config ...
    environment:
      - TZ=Europe/Bucharest
      - OLLAMA_HOST=http://ollama:11434
    depends_on:
      - ollama

  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    volumes:
      - ${HOME}/ollama:/root/.ollama
    # Only publish this if you want to reach it from the host too.
    # Don't publish it on a VPS.
    # ports:
    #   - "127.0.0.1:11434:11434"

Then pull a model and point a tool at it:

docker compose up -d
docker exec -it ollama ollama pull qwen3:14b
docker exec -it ollama ollama list

# From inside ai-tools, confirm the name resolves
docker exec -it ai-tools curl -s http://ollama:11434/api/tags | jq '.models[].name'

    deploy:
      resources:
        limits:
          memory: 12g

If you want the full Ollama stack with a web UI, our self-hosting Ollama with Docker Compose guide covers Open WebUI, model management, and the GPU setup.

Multiple container configurations

Separate containers per context keeps API keys and contexts from bleeding together:

~/docker-ai-tools-personal/
  ├── docker-compose.yml     # container_name: ai-tools-personal
  ├── Dockerfile
  └── .env                   # personal keys

~/docker-ai-tools-work/
  ├── docker-compose.yml     # container_name: ai-tools-work
  ├── Dockerfile
  └── .env                   # work keys, separate ~/websites mount

Change container_name and the mount paths in each file. Two containers with the same container_name will refuse to start - Compose errors with a name conflict, which is at least a clear failure.

Sharing containers with teams

cd ~/docker-ai-tools
git init

Create a .gitignore before the first commit:

cat > .gitignore <<'EOF'
.env
dev-home/
websites/
EOF

git add Dockerfile docker-compose.yml .gitignore
git commit -m "Add AI tools container config"

A teammate then runs:

git clone <your-repo>
cd <your-repo>
cp .env.example .env    # fill in their own keys
mkdir -p ~/dev-home ~/websites
docker compose up -d
docker exec -it ai-tools bash

Same Node, same Python, same installed tools. That’s the reproducible dev environment part of this, and it’s why committing the Dockerfile is worth the five minutes.

IDE integration

The container is where tools execute. Your editor stays on the host, where your font rendering, extensions, and keybindings already live.

VS Code Dev Containers for AI agents

Dev Containers let VS Code run its server inside the same container the agent uses, so the integrated terminal, the tasks, and the agent all see identical runtimes. Create ~/docker-ai-tools/.devcontainer/devcontainer.json:

{
  "name": "ai-tools",
  "dockerComposeFile": ["../docker-compose.yml"],
  "service": "ai-tools",
  "workspaceFolder": "/home/pn/app/websites",
  "remoteUser": "pn",
  "shutdownAction": "stopCompose",
  "customizations": {
    "vscode": {
      "extensions": ["esbenp.prettier-vscode", "dbaeumer.vscode-eslint"]
    }
  }
}

Steps:

1. Install the Dev Containers extension (the old “Remote - Containers” name is gone).
2. Open the ~/docker-ai-tools folder in VS Code.
3. Run Dev Containers: Reopen in Container.

If VS Code complains that the container already exists, you have it running from docker compose up -d. Run docker compose down first - Dev Containers wants to own the lifecycle.

For a terminal-based alternative on macOS aimed at agent workflows, see our cmux terminal for AI coding agents guide. And if you’d rather have the AI in the editor itself than in a container shell:

Direct file editing from the host

The simpler option, and the one most people end up using:

# On the host
code ~/websites/my-project

# In the container, the agent sees the changes immediately
cd ~/app/websites/my-project
amp "Refactor this component"

Bind mounts don’t sync - they are the same inode. There is no “waiting for sync” step, and no chance of a stale copy on one side.

Troubleshooting

# On the host
id -u
ls -lan ~/websites | head -3

# In the container
docker exec -it ai-tools id

sudo chown -R 1000:1000 ~/dev-home ~/websites

    user: "1002:1002"
    environment:
      - HOME=/home/pn

chcon -Rt container_file_t ~/dev-home ~/websites

docker compose logs --tail 50
docker logs ai-tools

podman compose logs --tail 50
podman logs ai-tools

droid
# then /login; if it prints a URL, paste that URL into your host browser

docker inspect ai-tools --format '{{json .Mounts}}' | jq
docker inspect ai-tools --format '{{.HostConfig.Privileged}}'

podman inspect ai-tools --format '{{json .Mounts}}' | jq

/home/you/dev-home  ->  /home/pn
/home/you/websites  ->  /home/pn/app/websites

Installing missing commands in the container

Base images are minimal on purpose. You’ll hit command not found the first time an agent wants rg, ffmpeg, or a Postgres client:

bash: rg: command not found
bash: psql: command not found

Two ways to fix it.

Option 1: install temporarily (quick fix)

# Enter as root
docker exec -it --user root ai-tools bash

# Always update the index first, or apt can't find the package
apt-get update
apt-get install -y ripgrep postgresql-client

exit
docker exec -it ai-tools bash

# Enter as root
podman exec -it --user root ai-tools bash

apt-get update
apt-get install -y ripgrep postgresql-client

exit
podman exec -it ai-tools bash

Option 2: update the Dockerfile and rebuild (permanent)

Add the package to the apt-get install line and rebuild:

RUN apt-get update && apt-get install -y --no-install-recommends \
    git \
    jq \
    curl \
    vim \
    nano \
    htop \
    tree \
    ripgrep \
    rsync \
    postgresql-client \
    ffmpeg \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

Then:

cd ~/docker-ai-tools
docker compose build
docker compose up -d
docker exec -it ai-tools bash

# Verify
rg --version
psql --version

cd ~/podman-ai-tools
podman compose build
podman compose up -d
podman exec -it ai-tools bash

# Verify
rg --version
psql --version

Common packages you might need

Security best practices for sandboxed AI agents

Your container config is a capability set. Everything in this list reduces what the agent can do if it goes wrong.

Read-only mounts and resource limits

Two compose changes that cut the blast radius without breaking anything:

services:
  ai-tools:
    # ... your existing config ...
    security_opt:
      - no-new-privileges:true   # blocks setuid escalation inside the container
    mem_limit: 8g                # kill the process instead of the host
    cpus: 4
    pids_limit: 512              # stops fork bombs from taking down the host

Verify the flags actually applied:

docker inspect ai-tools \
  --format 'mem={{.HostConfig.Memory}} pids={{.HostConfig.PidsLimit}} sec={{.HostConfig.SecurityOpt}}'

Expected: mem=8589934592, pids=512, and [no-new-privileges:true]. If mem=0, the limit didn’t take and the agent can consume all host RAM.

Now the stronger version, for when the agent only needs to read a reference tree:

    volumes:
      - ${HOME}/dev-home:/home/pn
      - ${HOME}/websites:/home/pn/app/websites
      - ${HOME}/reference-docs:/home/pn/reference:ro   # read-only

docker exec -it ai-tools sh -c 'touch /home/pn/reference/x' should fail with Read-only file system. That’s the test.

Environment variables and API keys

Keep keys out of the image and out of git. Compose reads .env automatically for variable substitution, and env_file injects the values into the container:

# docker-compose.yml or podman-compose.yml
services:
  ai-tools:
    env_file:
      - .env
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - GEMINI_API_KEY=${GEMINI_API_KEY}

# ~/.env - never commit this
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=...

The other direction matters too: don’t pass your whole host environment into the container. env_file: .env with five named keys is deliberate. docker run -e $(env) is handing the agent your AWS session token.

If you want the mechanics of ARG vs ENV vs Compose substitution, our guide on using ARG and ENV for environment variables in Docker Compose covers the differences and the override order.

Cleaning up

Remove container and images

# Stop and remove the container
docker compose down

# Remove the built image
docker rmi ai-tools:latest

# Remove dangling images, stopped containers, and unused networks
docker system prune

# Also remove unused volumes - read the warning below first
docker system prune -a --volumes

podman compose down
podman rmi ai-tools:latest
podman system prune

If Docker’s disk usage keeps climbing and prune isn’t enough, the culprit is usually the overlay2 layer store. We covered reclaiming disk space from /var/lib/docker/overlay2 separately.

For a quick reference of the commands you’ll actually type, our essential Docker commands list is worth bookmarking.

Start fresh

docker compose down
docker rmi ai-tools:latest

# Optional: reset configs and auth state
# This deletes every CLI config and login in the container home
rm -rf ~/dev-home/*

# Optional: reset the image cache entirely
docker builder prune -af

# Rebuild
docker compose build --no-cache
docker compose up -d

That rm -rf ~/dev-home/* is the one irreversible step in this whole guide. It wipes your auth tokens and tool configs. ~/websites is untouched.

Docker vs Podman for AI tooling

The honest summary: for this use case the difference is smaller than the internet suggests. Both run this exact compose file, both support the same image, and both give you the isolation you’re here for.

Pick Docker if: your team already runs it, you want the largest ecosystem of examples and CI integrations, or you’re on macOS and want the smoothest Desktop experience.

Pick Podman if: you’re on Fedora/RHEL, you want rootless containers without extra configuration, or you care that there’s no always-on root daemon to target.

For a container that runs an agent with shell access, the “no persistent root process and no Docker socket” argument is the one that actually matters for security. The mechanism is simple: if the agent finds /var/run/docker.sock inside its container, it can start a privileged container and be root on your host in about three commands.

The full breakdown of architecture, licensing, and migration paths is in our Podman vs Docker compared article.

Real-world usage examples

Example 1: Factory.ai with custom models

# Inside the container
cd ~/app/websites/my-app

droid

# In the Droid prompt, pick your model
/model
# Choose "Claude Sonnet 4.5" from custom models

"Add user authentication with Supabase, including sign-up, login, and protected routes"

The value of the custom model config: you can point Factory at a cheap aggregator for routine edits and at a frontier model only when you need it, without changing anything on the host.

Example 2: Amp with project context

cd ~/app/websites/nextjs-blog

cat > AGENTS.md <<'EOF'
# Project: Next.js Blog

## Tech stack
- Next.js 15
- TypeScript
- Tailwind CSS
- MDX for blog posts

## Architecture
- App Router
- Server Components by default
- Client Components only when needed

## Commands
- Dev: npm run dev
- Build: npm run build
- Test: npm test
EOF

amp "Add a comments section using Supabase"

AGENTS.md is the cheapest context win available. It’s a file in the project, so it works for every agent that reads it, and it works identically inside the container.

Example 3: multiple AI tools in sequence

# One agent implements
amp "Create a React component for a product card"

# Another reviews
claude "Review the ProductCard component and suggest performance improvements"

# A third writes tests
droid "Generate unit tests for ProductCard.tsx"

Different models are good at different things, and running them against the same checkout means each one sees the previous one’s work. It’s also a cheap way to sanity-check an agent’s output against a second opinion.

If you want the next step - letting an assistant drive Docker deployments on a server - that’s a different problem with a bigger blast radius, and we wrote about letting an AI assistant deploy Docker apps separately.

Best practices for AI CLI tools in containers

Frequently asked questions

# Terminal 1
docker exec -it ai-tools bash
cd ~/app/websites/project1
amp "Implement feature X"

# Terminal 2, same container
docker exec -it ai-tools bash
cd ~/app/websites/project2
claude "Review the auth code"

# Inside the container
claude update
amp update
droid update

# npm-installed tools
npm update -g @google/gemini-cli
npm update -g @github/copilot

# .github/workflows/ai-review.yml
name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build AI tools image
        run: docker compose build
      - name: Run AI review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          docker compose up -d
          docker exec ai-tools claude -p "Review this PR for code quality and list any bug risks"

# Python 3.14 with Node 26 (what this guide uses)
FROM nikolaik/python-nodejs:python3.14-nodejs26-bookworm

# Python 3.13 with Node 26
FROM nikolaik/python-nodejs:python3.13-nodejs26-bookworm

# Slim variant - smaller, no build toolchain
FROM nikolaik/python-nodejs:python3.14-nodejs26-slim

Conclusion

Containerizing AI CLI tools gives you a sandbox you can afford to be careless in. Not a security boundary against a determined attacker, but a boundary against the failure mode that actually happens: an agent that runs a command it shouldn’t have.

What you end up with:

The three things worth doing differently from the 2025 version of this guide: move to python3.14-nodejs26-bookworm for the base image, stop installing Ollama inside the agent container, and don’t bind mount anything you wouldn’t hand over in a shell prompt.

If you’re building out the rest of the stack, the follow-ups that matter most are Podman vs Docker compared if you’re still choosing an engine, OpenCode setup guide or Amp Code AI coding agent for the tool side, and the best AI coding tools and agents in 2026 if you’d rather compare before committing.