Skip to content

Commit 7a8d037

Browse files
justinyoojustinyoo
committed
docs: add sandbox demo guides
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: dcedf6b4-0ae1-4914-ba14-77e4bac4c4a9
1 parent 8c3595c commit 7a8d037

9 files changed

Lines changed: 1237 additions & 0 deletions

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@
2323
# Presentation source and referenced assets.
2424
!ai-agent-sandboxing.md
2525
!assets/**
26+
!docs/
27+
!docs/**
2628

2729
# Generated GitHub Pages entrypoint.
2830
index.html

‎README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,22 @@ The primary presentation was prepared for various conferences and meetups, and c
1111
├── .github/
1212
├── assets/
1313
├── ai-agent-sandboxing.md # Marp presentation source
14+
├── docs/ # Demo setup, runbooks, and recovery guides
1415
├── index.html # Generated presentation (ignored)
1516
├── LICENSE
1617
└── README.md
1718
```
1819

20+
## Demo guides
21+
22+
The [demo documentation index](docs/README.md) provides two complete,
23+
sequential walkthroughs:
24+
25+
| Demo | Setup | Runbook | Validation and recovery |
26+
| --- | --- | --- | --- |
27+
| 1. Java modernization in a Docker Sandbox | [Setup](docs/demo-1-setup.md) | [Runbook](docs/demo-1-runbook.md) | [Validation](docs/demo-1-validation-and-recovery.md) |
28+
| 2. Copilot CLI in an ACA Sandbox | [Setup](docs/demo-2-setup.md) | [Runbook](docs/demo-2-runbook.md) | [Validation](docs/demo-2-validation-and-recovery.md) |
29+
1930
## Preview the presentation
2031

2132
1. Install Node.js 22 or later, then generate an HTML presentation:

‎docs/README.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# AI agent sandboxing demo guides
2+
3+
These documents support the live demos in
4+
[`ai-agent-sandboxing.md`](../ai-agent-sandboxing.md).
5+
6+
## Demo 1: Java modernization in a Docker Sandbox
7+
8+
1. [Environment setup](demo-1-setup.md) - install `sbx`, prepare credentials,
9+
clone the sample, and establish a clean baseline.
10+
2. [Live demo runbook](demo-1-runbook.md) - create the clone-mode sandbox,
11+
modernize the Java application, and show the isolation evidence.
12+
3. [Validation and recovery](demo-1-validation-and-recovery.md) - inspect,
13+
preserve, troubleshoot, and clean up the result.
14+
15+
## Demo 2: Copilot CLI in an ACA Sandbox
16+
17+
1. [Environment setup](demo-2-setup.md) - install `aca`, prepare Azure RBAC and
18+
credentials, and verify the Copilot disk image.
19+
2. [Live demo runbook](demo-2-runbook.md) - create the managed sandbox,
20+
generate a UI design plan, and prove that state survives stop and resume.
21+
3. [Validation and recovery](demo-2-validation-and-recovery.md) - export
22+
evidence, snapshot state, troubleshoot failures, and clean up Azure
23+
resources.
24+
25+
## Demo 1 outcome
26+
27+
The demo should make four points visible:
28+
29+
- Copilot CLI runs inside an isolated microVM.
30+
- The modernization agent assesses, plans, and executes the Java upgrade.
31+
- The agent uses a private Git clone and cannot write to the host repository.
32+
- The sandbox has its own Docker daemon and policy-controlled network access.
33+
34+
The sample application is
35+
[`UW-Madison-DoIT/uportal-messaging`](https://github.com/UW-Madison-DoIT/uportal-messaging).
36+
Its current baseline makes the change easy to explain: Java 8, Spring Boot
37+
1.5.9.RELEASE, Maven, WAR packaging, and an OpenJDK 8 Travis CI build.
38+
39+
## Demo 2 outcome
40+
41+
Demo 2 runs Copilot CLI in an Azure Container Apps Sandbox, asks it to create a
42+
design-only plan for
43+
[`devkimchi/battle-school-lunch`](https://github.com/devkimchi/battle-school-lunch),
44+
stops the remote sandbox, and resumes the same sandbox with its filesystem
45+
state intact.
46+
47+
## References
48+
49+
- [Get started with Docker Sandboxes](https://docs.docker.com/ai/sandboxes/get-started/)
50+
- [Run GitHub Copilot in a Docker Sandbox](https://docs.docker.com/ai/sandboxes/agents/copilot/)
51+
- [Docker Sandbox installation](https://docs.docker.com/ai/sandboxes/install/)
52+
- [Docker Sandbox isolation](https://docs.docker.com/ai/sandboxes/security/isolation/)
53+
- [Modernize Java apps with GitHub Copilot modernization](https://learn.microsoft.com/azure/developer/java/migration/github-copilot-app-modernization-for-java-copilot-cli)
54+
55+
Commands and prerequisites were checked against the linked documentation on
56+
August 24, 2026.

‎docs/demo-1-runbook.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
# Demo 1: Java modernization in a Docker Sandbox
2+
3+
This runbook follows the Demo 1 sequence in
4+
[`ai-agent-sandboxing.md`](../ai-agent-sandboxing.md). Use two terminals:
5+
Terminal A for Copilot CLI and Terminal B for inspection.
6+
7+
> [!IMPORTANT]
8+
> Run this demo in clone mode. Direct mode protects the host operating system,
9+
> but it gives the agent read-write access to the host working tree.
10+
11+
## What the demo proves
12+
13+
- Copilot CLI runs inside an isolated microVM.
14+
- The modernization agent assesses, plans, and executes the Java upgrade.
15+
- The agent works in a private clone and cannot write to the host repository.
16+
- The sandbox has its own Docker daemon and policy-controlled network access.
17+
18+
## Before you begin
19+
20+
Complete the [Demo 1 environment setup](demo-1-setup.md). Confirm that:
21+
22+
- `sbx`, GitHub CLI, and Git are available.
23+
- Docker and GitHub authentication succeed.
24+
- The **Balanced** network policy is active.
25+
- `uportal-messaging` is clean and checked out on `demo/baseline`.
26+
- No stale `java-modernize` sandbox contains unpreserved work.
27+
28+
## 1. Start Copilot in a private clone
29+
30+
From the host checkout of `uportal-messaging`, run in Terminal A:
31+
32+
```powershell
33+
sbx secret set github --command 'gh auth token'
34+
sbx run --clone --name java-modernize copilot .
35+
```
36+
37+
On first use, choose the **Balanced** network preset when prompted.
38+
39+
`--clone` is the important boundary:
40+
41+
- `/run/sandbox/source` is a read-only mount of the host repository.
42+
- Copilot works in a separate read-write clone inside the microVM.
43+
- `sbx` adds a `sandbox-java-modernize` Git remote to the host repository.
44+
- Nothing reaches the host working tree until an explicit fetch, checkout, or
45+
push.
46+
47+
Copilot's Docker Sandbox template starts with its approval-skipping mode. This
48+
does not remove the microVM, workspace, credential, Docker daemon, or network
49+
boundaries.
50+
51+
## 2. Prepare the modernization agent
52+
53+
### Install the plugin
54+
55+
In the Copilot CLI session, enter:
56+
57+
```text
58+
/plugin marketplace add microsoft/github-copilot-modernization
59+
/plugin install github-copilot-modernization@github-copilot-modernization
60+
/plugin list
61+
```
62+
63+
Confirm that the list contains:
64+
65+
```text
66+
github-copilot-modernization@github-copilot-modernization
67+
```
68+
69+
The equivalent non-interactive shell commands are:
70+
71+
```bash
72+
copilot plugin marketplace add microsoft/github-copilot-modernization
73+
copilot plugin install github-copilot-modernization@github-copilot-modernization
74+
```
75+
76+
### Select the orchestrator
77+
78+
Enter `/agent`, then select:
79+
80+
```text
81+
github-copilot-modernization:modernize
82+
```
83+
84+
Do not run the upgrade with the default Copilot agent. The `modernize` agent
85+
provides the assessment, planning, specialized executors, retries, and
86+
per-task commits used in this demo.
87+
88+
## 3. Run the modernization
89+
90+
Use this prompt:
91+
92+
```text
93+
Before making changes, create and switch to a branch named demo/modernized.
94+
Upgrade this application to Java 21 and Spring Boot 4.1. Assess the current
95+
application, create a reviewable plan, execute the plan, update tests and build
96+
configuration, run the relevant Maven verification, check dependencies for
97+
known vulnerabilities, and commit each completed task separately. Do not push
98+
the branch or open a pull request.
99+
```
100+
101+
The expected workflow is:
102+
103+
1. **Assessment** - discovers Java version, framework, dependencies, and risks;
104+
writes `.github/modernize/assessment/`.
105+
2. **Planning** - writes `.github/modernize/<app>/plan.md` and `tasks.json`.
106+
3. **Execution** - delegates tasks, updates the application, verifies the
107+
build, and creates detailed task commits.
108+
109+
A specific upgrade prompt can go directly to planning and execution. Asking
110+
for assessment explicitly keeps all three phases visible for the demo.
111+
112+
## 4. Inspect the sandbox while the agent works
113+
114+
In Terminal B:
115+
116+
```powershell
117+
sbx ls
118+
sbx policy ls
119+
sbx exec -it java-modernize bash
120+
```
121+
122+
Inside the sandbox shell:
123+
124+
```bash
125+
pwd
126+
node --version
127+
git branch --show-current
128+
git status --short
129+
docker info
130+
find .github/modernize -maxdepth 3 -type f -print 2>/dev/null
131+
```
132+
133+
Show that the host source mount is read-only:
134+
135+
```bash
136+
touch /run/sandbox/source/__sandbox-write-test
137+
```
138+
139+
The command should fail with a read-only filesystem error. Do not use a path
140+
inside the private clone for this test; the private clone is intentionally
141+
writable.
142+
143+
Show the isolated Docker daemon without changing the host:
144+
145+
```bash
146+
docker run --rm hello-world
147+
docker ps -a
148+
```
149+
150+
The container and image exist only in the sandbox's Docker Engine. Docker
151+
Sandboxes do not mount the host Docker socket.
152+
153+
Exit the inspection shell:
154+
155+
```bash
156+
exit
157+
```
158+
159+
Run `sbx` with no arguments on the host to open the dashboard. Switch to its
160+
network panel to show allowed and denied outbound connections and the rules
161+
that made each decision.
162+
163+
## 5. Prove that the host stayed clean
164+
165+
While the agent's commits remain in the private clone, run from the host
166+
checkout:
167+
168+
```powershell
169+
git status --short
170+
git branch --show-current
171+
git remote --verbose
172+
```
173+
174+
Expected result:
175+
176+
- `git status --short` prints nothing.
177+
- The host remains on `demo/baseline`.
178+
- A `sandbox-java-modernize` remote is present.
179+
180+
## 6. Verify the result
181+
182+
After the modernization agent finishes, use the inspection shell or ask the
183+
agent to report:
184+
185+
```bash
186+
git branch --show-current
187+
git status --short
188+
git --no-pager log --oneline --decorate -15
189+
find .github/modernize -maxdepth 3 -type f -print
190+
```
191+
192+
Confirm that the branch is `demo/modernized`, the expected assessment and plan
193+
artifacts exist, verification results are reported, and task commits are
194+
present.
195+
196+
## 7. Preserve evidence and clean up
197+
198+
Continue with
199+
[Demo 1 validation and recovery](demo-1-validation-and-recovery.md) to:
200+
201+
1. Fetch `sandbox-java-modernize/demo/modernized`.
202+
2. Review application, build, CI, and modernization artifacts.
203+
3. Materialize only the reviewed branch on the host.
204+
4. Stop and remove the sandbox after its work is preserved.
205+
206+
## Troubleshooting
207+
208+
Use the
209+
[Demo 1 troubleshooting guide](demo-1-validation-and-recovery.md#troubleshooting)
210+
for plugin installation, Java discovery, network policy, Maven, sandbox mode,
211+
and fetch failures.
212+
213+
## References
214+
215+
- [Get started with Docker Sandboxes](https://docs.docker.com/ai/sandboxes/get-started/)
216+
- [Run GitHub Copilot in a Docker Sandbox](https://docs.docker.com/ai/sandboxes/agents/copilot/)
217+
- [Docker Sandbox isolation](https://docs.docker.com/ai/sandboxes/security/isolation/)
218+
- [Use Git with Docker Sandboxes](https://docs.docker.com/ai/sandboxes/workflows/git/)
219+
- [Modernize Java apps with GitHub Copilot modernization](https://learn.microsoft.com/azure/developer/java/migration/github-copilot-app-modernization-for-java-copilot-cli)
220+
221+
Commands and behavior were checked against the linked documentation on
222+
August 24, 2026.
223+
224+
## Navigation
225+
226+
[Previous: Demo 1 environment setup](demo-1-setup.md) |
227+
[Next: Demo 1 validation and recovery](demo-1-validation-and-recovery.md)

0 commit comments

Comments
 (0)