More Amplifier Stories

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

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.

1Is Docker installed?
2Is the daemon running?
3Does the user have permissions?
4What base image to use?
5What docker run flags?
6How to mount the project?
7Forward API keys and env vars?
8Forward git credentials?
9Forward GH CLI auth?
10Forward SSH keys?
11Shell preferences & dotfiles?
12How does the user connect?
13What about cleanup?
14What if they want to save state?
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

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.

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

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

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.

🐍
python
python:3.12-slim
+ uv + venv
🟢
node
node:20-slim
+ corepack
🦀
rust
rust:1-slim
+ build-essential
🔵
go
golang:1.22
ready to go
🖥️
general
ubuntu:24.04
full dev tools
amplifier
python:3.12-slim
+ amplifier CLI
🔍
try-repo
auto-detected
reads your repo
🧹
clean
ubuntu:24.04
no forwarding

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.shsetup.shMakefile → symlinks.

🛡️ Security

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

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.

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.

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

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)

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)

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
More Amplifier Stories More Amplifier Stories