Platform Feature

Shadow Environments

Isolated containers that snapshot your local repos.
Test your changes before you push.

Alpha

January 2026 · Brian Krabach

The Problem

Testing local changes is risky

Polluted Environment

Your local machine has years of accumulated state. "Works on my machine" is the oldest lie in software.

Cross-Repo Dependencies

Changing amplifier-core? Need to test it with amplifier-foundation. Local symlinks are fragile and error-prone.

Push to Test

Often the only way to really test is to push and wait for CI. That's slow, public, and clutters your git history.

The Solution

Shadow environments

Security-hardened Docker/Podman containers with an embedded Gitea
server that snapshots your exact working tree—including
untracked and deleted files—into a clean test environment.

How It Works

Selective git URL rewriting + embedded Gitea

Your Local Repo

~/repos/core

→

Gitea Server
Snapshot

→

Container

Isolated Test

            Git is configured to rewrite only the specific GitHub URLs you specify to the embedded Gitea server. Your local changes appear as the "real" repo inside the container. All other dependencies fetch from real GitHub.
        

Usage

Simple CLI operations

# Create shadow with local source
amplifier-shadow create --local ~/repos/amplifier-core:microsoft/amplifier-core

# Run commands inside the container
amplifier-shadow exec <id> "uv pip install git+https://github.com/microsoft/amplifier"
amplifier-shadow exec <id> "amplifier run 'Hello from shadow'"

# Your local amplifier-core is used automatically!

# See what changed, open a shell, or clean up
amplifier-shadow diff <id>
amplifier-shadow shell <id>
amplifier-shadow destroy <id>

Key Features

What you get

✓ Exact working tree snapshots (untracked + deleted files included)
✓ Full git history preserved (pinned commits work)
✓ Multiple local sources in one shadow
✓ API keys auto-passed from host environment
✓ File injection/extraction for iterating
✓ Security-hardened containers (dropped capabilities, no-new-privileges)

Multi-Repo

Test changes across repositories

# Full-stack Amplifier integration test
amplifier-shadow create \
  --local ~/repos/amplifier-core:microsoft/amplifier-core \
  --local ~/repos/amplifier-foundation:microsoft/amplifier-foundation \
  --local ~/repos/amplifier-app-cli:microsoft/amplifier-app-cli

# Inside the shadow:
# - amplifier-core       → YOUR local snapshot
# - amplifier-foundation → YOUR local snapshot
# - amplifier-app-cli    → YOUR local snapshot
# - everything else      → real GitHub

amplifier-shadow exec <id> "uv tool install git+https://github.com/microsoft/amplifier"
# All three local repos resolve to your code!

Trust But Verify

Know your local code is actually used

Snapshot Commits

The create and status commands return the exact commit hash captured from your local repo.

Install Output

When pip/uv installs a package, it shows the resolved commit. Match it against snapshot_commits to verify.

Smoke Test Agent

The shadow-smoke-test agent independently validates that your local sources are actually being used inside the container.

11 CLI Commands

create, add-source, exec, shell, list, status, diff, extract, inject, destroy, build — full lifecycle management.

Development Velocity

Built in 29 days

72

Commits

66 in first 12 days

7,226

Lines of Python

2,778 src · 1,394 tool · 3,054 tests

1

Contributor

Brian Krabach (100%)

microsoft/amplifier-bundle-shadow · Jan 6 – Feb 4, 2026
Also integrated into amplifier-foundation (21 additional commits)

Sources

Research Methodology

Data as of: February 20, 2026

Feature status: Alpha (pyproject.toml: "Development Status :: 3 - Alpha")

Bundle version: 0.2.0 (bundle.yaml) / 0.1.0 (pyproject.toml)

Research performed:

Git log: git log --oneline on unshallowed amplifier-bundle-shadow cache (72 commits)
Contributors: git log --format="%an" | sort | uniq -c (1 contributor: Brian Krabach)
Line counts: find . -name "*.py" | wc -l (22 files, 7,226 lines total)
Breakdown: find src/ tests/ modules/ -name "*.py" -exec cat {} + | wc -l per directory
Timeline: git log --reverse --format="%ai" first commit Jan 6, last Feb 4 = 29 days
Foundation integration: git log --all --grep="shadow" in amplifier-foundation (21 commits)
Feature details: README.md, bundle.yaml, behaviors/shadow.yaml from cached repo

Gaps: Shadow bundle cache was shallow-cloned; full history retrieved via git fetch --unshallow. PR count (2) reflects merge commits only; additional PRs may exist without merge commit messages.

Primary contributor: Brian Krabach — 72/72 commits (100%)

Test before you push.

Isolated. Reproducible. Verified.

github.com/microsoft/amplifier-bundle-shadow
Part of the Amplifier ecosystem