amplifier-bundle-containers

One tool call.
Full provisioning.
Zero friction.

General-purpose container management for AI agents.
Spin up isolated Docker/Podman environments complete with credential forwarding, smart language defaults, and dotfiles integration.

v0.1.0 Active 160 tests 20 operations 8 purpose profiles

The Problem

14 manual steps.
Every. Single. Time.

Every time an AI assistant needs to set up a container, it fumbles through the same checklist — and forgets everything by next session.

1	Is Docker installed?
2	Is the daemon running?
3	Does the user have permissions?
4	What base image to use?
5	What `docker run` flags?
6	How to mount the project?
7	Forward API keys and env vars?

8	Forward git credentials?
9	Forward GH CLI auth?
10	Forward SSH keys?
11	Shell preferences & dotfiles?
12	How does the user connect?
13	What about cleanup?
14	What if they want to save state?

The Solution

1

One tool call replaces fourteen steps.

The assistant says what it wants, and it works. Smart defaults handle the rest — image selection, mounts, credentials, security hardening — all in a single containers(create) call.

containers(create)

→

Preflight

→

Image + Cache

→

Provision

→

Report

Real-World Example

The self-improving system

Postgres database, two repos with install commands, config files, GitHub auth, and personal dotfiles — all in one call:

containers(create, name="self-improve",
    compose_content="services:\n  db:\n    image: postgres:16\n    environment:\n      POSTGRES_PASSWORD: dev\n    ports:\n      - '5432:5432'",
    repos=[
        {"url": "https://github.com/user/service-a",
         "install": "pip install -e ."},
        {"url": "https://github.com/user/service-b"},
    ],
    config_files={"/workspace/.storage.yaml": "provider: git\n"},
    forward_gh=True,
    dotfiles_repo="https://github.com/user/dotfiles")

Compose services start first → primary container joins the network → repos clone → configs write → credentials forward → dotfiles install. One call.

Structured Output

You get a full provisioning report back.

Every step reports its status — the assistant knows exactly what succeeded, what was skipped, and what needs attention.

✅ compose Started 1 service on self-improve_default network

✅ env_passthrough 30 vars injected (ANTHROPIC_API_KEY, OPENAI_API_KEY, AZURE_*, …)

✅ forward_git Flattened host config (resolved includes), identity verified

✅ forward_gh GH_TOKEN + GITHUB_TOKEN injected as container env vars

⏭️ forward_ssh Not requested (opt-in)

✅ dotfiles Cloned user/dotfiles, ran install.sh

✅ repos Cloned 2 repos, installed service-a

✅ config_files Wrote 1 config file

Capabilities

20 operations. Everything you need.

Core Lifecycle

preflight create exec exec_interactive_hint list status destroy destroy_all

File Transfer & State

copy_in copy_out snapshot restore

Networks & Background Exec

create_network destroy_network exec_background exec_poll exec_cancel

Health & Cache

wait_healthy cache_clear + Docker Compose

Smart Defaults

8 purpose profiles. Say what, not how.

Each profile pre-selects the right base image, packages, and setup commands. try-repo even auto-detects the language from your repo.

Provisioning Pipeline

Your identity, forwarded securely.

Three layers of provisioning — from explicit env vars to full dotfiles repos. Security hardened by default.

⚙️ Git Config

Flattens the host's git config via git config --list --global --includes, resolving all [include] chains. Filters out host-specific sections and constructs a clean, self-contained .gitconfig. Identity guaranteed.

🔑 GitHub Tokens

Extracts tokens via gh auth token and injects both GH_TOKEN and GITHUB_TOKEN as real container env vars via -e flags at docker run time. Verified in the provisioning report.

🔒 SSH Keys

Opt-in bind mount with corrected permissions: 700 dir, 600 keys, 644 pub.

🌍 API Keys

Auto-passthrough for OPENAI_*, ANTHROPIC_*, AZURE_*, and dozens more. 30+ env vars forwarded without manual setup.

🏠 Dotfiles

Clone your dotfiles repo. Auto-detects install script: install.sh → setup.sh → Makefile → symlinks.

🛡️ Security

no-new-privileges, 4GB memory cap, PID limits, bridge network only. Never privileged.

Power Features

Native Compose. Background exec. Health checks.

🐳

Docker Compose

LLMs already know compose YAML from training data. Pass compose_content inline — the tool writes the file, starts services, and connects your primary container to the same network.

📦

Multi-Repo Cloning

Clone multiple repos with optional install commands. Each repo gets its own directory in /workspace.

📄

Config File Placement

Write arbitrary config files to any path inside the container. Directories are created automatically.

👤

Two-Phase User Model

Root for setup (package install, config). Mapped UID:GID user for exec. Files owned correctly on the host.

⏳

Background Exec + Polling

exec_background returns a job_id immediately. Poll with exec_poll. Cancel with exec_cancel. No blocking.

💚

wait_healthy

Poll a health-check command until the service is ready. Configurable interval and retries. Perfect for startup ordering.

💾

Snapshot & Restore

Commit container state as a tagged image. Restore later from any snapshot. Persistent work across sessions.

🚀

Image Caching

First create builds and caches the purpose image. Subsequent creates reuse it — version-hashed for correctness.

🔍

Try-Repo Detection

Point at a GitHub URL. Auto-detects Cargo.toml, pyproject.toml, package.json, or go.mod and selects the right profile.

Architecture

Thin bundle pattern. Clean separation.

The bundle is a composition layer. The tool module does the work. Each concern has its own class.

Bundle bundle.md — composition root. Includes behaviors, agents, and context. 8 lines.

Behavior containers.yaml — wires tool module + agent + context documents.

Agent container-operator.md — specialist agent for complex orchestration scenarios.

Tool Module ContainersTool — 1,437 lines. 20 operations. The core engine.

Runtime ContainerRuntime — Docker/Podman auto-detection and CLI abstraction.

Provisioner ContainerProvisioner — 511 lines. Credentials, dotfiles, repos, config files.

Compose ComposeManager — Docker Compose v2 lifecycle: up, down, ps, network discovery.

Metadata MetadataStore — JSON persistence in ~/.amplifier/containers/. Tracks state across sessions.

Built With Amplifier

This project was built
in a single session.

5 phases. 160 tests. 10 bugfixes from real-world testing. The AI designed the architecture, wrote every module, ran every test, debugged every failure, and wrote the documentation.

Based on development session records. Metrics from original build.

Phase 1
Core MVP

→

Phase 2
Production

→

Phase 3
User Model

→

Phase 4
GPU + Health

→

Phase 5
Compose + Repos

54

→ 103 → 123 → 133 → 160 tests

By The Numbers

Measured. Tested. Shipped.

20

Operations

8

Purpose Profiles

160

Tests

5

Phases

144

Unit Tests

16

Integration Tests

1,437

Lines (Tool Core)

511

Lines (Provisioner)

Sources

Research Methodology

Data as of: February 20, 2026

Feature status: Active

Research performed:

GitHub: gh repo view microsoft/amplifier-bundle-containers — confirmed active, last updated 2026-02-17
Local cache: found in ~/.amplifier/cache/
Metrics (160 tests, 20 ops, 1,437 lines, 511 lines) from original build session — not independently re-verified

Gaps: Metrics sourced from build session, not independently verified from current repo state. Test count and line counts may have changed since original authoring.

Primary contributors: Built with Amplifier (AI-assisted development)

Get Started

Add it in
one command.

click to copy amplifier bundle add \ git+https://github.com/microsoft/amplifier-bundle-containers@main \ --app

Then just ask your assistant to create a container. It handles the rest.

// That's it. You're ready.
containers(create, purpose="python")

// Or try a repo directly:
containers(create,
    purpose="try-repo",
    repo_url="https://github.com/microsoft/amplifier-core")

GitHub → · Documentation · Design Doc

One tool call.Full provisioning.Zero friction.

14 manual steps.Every. Single. Time.