@@ -16,13 +16,15 @@ Runnable examples live in [`examples/`](./examples).
1616- [ Secrets with Devbox and Agent Gateway] ( #secrets-with-devbox )
1717
1818<a id =" blueprint-with-build-context " ></a >
19+
1920## Blueprint with Build Context
2021
2122** Use case:** Create a blueprint using the object store to provide docker build context files, then verify files are copied into the image.
2223
2324** Tags:** ` blueprint ` , ` object-store ` , ` build-context ` , ` devbox ` , ` cleanup `
2425
2526### Workflow
27+
2628- Create a temporary directory with sample application files
2729- Upload the directory to object storage as build context
2830- Create a blueprint with a Dockerfile that copies the context files
@@ -31,28 +33,33 @@ Runnable examples live in [`examples/`](./examples).
3133- Shutdown devbox and delete blueprint and storage object
3234
3335### Prerequisites
36+
3437- ` RUNLOOP_API_KEY `
3538
3639### Run
40+
3741``` sh
3842yarn tsn -T examples/blueprint-with-build-context.ts
3943```
4044
4145### Test
46+
4247``` sh
4348yarn test:examples
4449```
4550
4651** Source:** [ ` examples/blueprint-with-build-context.ts ` ] ( ./examples/blueprint-with-build-context.ts )
4752
4853<a id =" devbox-from-blueprint-lifecycle " ></a >
54+
4955## Devbox From Blueprint (Run Command, Shutdown)
5056
5157** Use case:** Create a devbox from a blueprint, run a command, fetch logs, validate output, and cleanly tear everything down.
5258
5359** Tags:** ` devbox ` , ` blueprint ` , ` commands ` , ` logs ` , ` cleanup `
5460
5561### Workflow
62+
5663- Create a blueprint
5764- Fetch blueprint build logs
5865- Create a devbox from the blueprint
@@ -62,28 +69,33 @@ yarn test:examples
6269- Shutdown devbox and delete blueprint
6370
6471### Prerequisites
72+
6573- ` RUNLOOP_API_KEY `
6674
6775### Run
76+
6877``` sh
6978yarn tsn -T examples/devbox-from-blueprint-lifecycle.ts
7079```
7180
7281### Test
82+
7383``` sh
7484yarn test:examples
7585```
7686
7787** Source:** [ ` examples/devbox-from-blueprint-lifecycle.ts ` ] ( ./examples/devbox-from-blueprint-lifecycle.ts )
7888
7989<a id =" devbox-mounts " ></a >
90+
8091## Devbox Mounts (Agent, Code, Object)
8192
8293** Use case:** Launch a devbox that combines an agent mount for Claude Code, a code mount for the Runloop CLI repo, and an object mount for startup files.
8394
8495** Tags:** ` devbox ` , ` mounts ` , ` agent ` , ` code ` , ` object ` , ` claude-code ` , ` agent-gateway ` , ` ttl `
8596
8697### Workflow
98+
8799- Create or reuse an agent by name
88100- Create a secret for an agent and route it through agent gateway
89101- Upload a temporary directory as a storage object with a TTL
@@ -93,29 +105,34 @@ yarn test:examples
93105- Shutdown the devbox and delete the temporary secret and object
94106
95107### Prerequisites
108+
96109- ` RUNLOOP_API_KEY `
97110- ` ANTHROPIC_API_KEY `
98111
99112### Run
113+
100114``` sh
101115ANTHROPIC_API_KEY=sk-ant-xxx yarn tsn -T examples/devbox-mounts.ts
102116```
103117
104118### Test
119+
105120``` sh
106121yarn test:examples
107122```
108123
109124** Source:** [ ` examples/devbox-mounts.ts ` ] ( ./examples/devbox-mounts.ts )
110125
111126<a id =" devbox-snapshots " ></a >
127+
112128## Devbox Snapshots (Suspend, Resume, Restore, Delete)
113129
114130** Use case:** Upload a file to a devbox, preserve it across suspend and resume, create a disk snapshot, restore multiple devboxes from that snapshot, mutate each copy independently, and delete the snapshot when finished.
115131
116132** Tags:** ` devbox ` , ` snapshot ` , ` suspend ` , ` resume ` , ` files ` , ` cleanup `
117133
118134### Workflow
135+
119136- Create a source devbox
120137- Upload a file and mutate it into a shared baseline
121138- Suspend and resume the source devbox
@@ -125,28 +142,33 @@ yarn test:examples
125142- Shutdown the devboxes and delete the snapshot
126143
127144### Prerequisites
145+
128146- ` RUNLOOP_API_KEY `
129147
130148### Run
149+
131150``` sh
132151yarn tsn -T examples/devbox-snapshots.ts
133152```
134153
135154### Test
155+
136156``` sh
137157yarn test:examples
138158```
139159
140160** Source:** [ ` examples/devbox-snapshots.ts ` ] ( ./examples/devbox-snapshots.ts )
141161
142162<a id =" devbox-tunnel " ></a >
163+
143164## Devbox Tunnel (HTTP Server Access)
144165
145166** Use case:** Create a devbox with a tunnel, start an HTTP server, and access the server from the local machine through the tunnel.
146167
147168** Tags:** ` devbox ` , ` tunnel ` , ` networking ` , ` http `
148169
149170### Workflow
171+
150172- Create a devbox with a tunnel
151173- Start an HTTP server inside the devbox
152174- Read the tunnel details from the devbox
@@ -155,28 +177,33 @@ yarn test:examples
155177- Shutdown the devbox
156178
157179### Prerequisites
180+
158181- ` RUNLOOP_API_KEY `
159182
160183### Run
184+
161185``` sh
162186yarn tsn -T examples/devbox-tunnel.ts
163187```
164188
165189### Test
190+
166191``` sh
167192yarn test:examples
168193```
169194
170195** Source:** [ ` examples/devbox-tunnel.ts ` ] ( ./examples/devbox-tunnel.ts )
171196
172197<a id =" mcp-github-tools " ></a >
198+
173199## MCP Hub + Claude Code + GitHub
174200
175201** Use case:** Connect Claude Code running in a devbox to GitHub tools through MCP Hub without exposing raw GitHub credentials to the devbox.
176202
177203** Tags:** ` mcp ` , ` devbox ` , ` github ` , ` commands ` , ` cleanup `
178204
179205### Workflow
206+
180207- Create an MCP config for GitHub
181208- Store GitHub token as a Runloop secret
182209- Launch a devbox with MCP Hub wiring
@@ -185,30 +212,35 @@ yarn test:examples
185212- Shutdown devbox and clean up cloud resources
186213
187214### Prerequisites
215+
188216- ` RUNLOOP_API_KEY `
189217- ` GITHUB_TOKEN (GitHub PAT with repo scope) `
190218- ` ANTHROPIC_API_KEY `
191219
192220### Run
221+
193222``` sh
194223GITHUB_TOKEN=ghp_xxx ANTHROPIC_API_KEY=sk-ant-xxx yarn tsn -T examples/mcp-github-tools.ts
195224```
196225
197226### Test
227+
198228``` sh
199229yarn test:examples
200230```
201231
202232** Source:** [ ` examples/mcp-github-tools.ts ` ] ( ./examples/mcp-github-tools.ts )
203233
204234<a id =" secrets-with-devbox " ></a >
235+
205236## Secrets with Devbox and Agent Gateway
206237
207238** Use case:** Use a normal secret for sensitive app data in the devbox and agent gateway for upstream API credentials that should never be exposed to the agent.
208239
209240** Tags:** ` secrets ` , ` devbox ` , ` agent-gateway ` , ` credentials ` , ` environment-variables ` , ` cleanup `
210241
211242### Workflow
243+
212244- Create a secret for application data that should be available inside the devbox
213245- Create a separate secret for an upstream API credential
214246- Create an agent gateway config for an upstream API
@@ -217,14 +249,17 @@ yarn test:examples
217249- Shutdown the devbox and delete the gateway config and both secrets
218250
219251### Prerequisites
252+
220253- ` RUNLOOP_API_KEY `
221254
222255### Run
256+
223257``` sh
224258yarn tsn -T examples/secrets-with-devbox.ts
225259```
226260
227261### Test
262+
228263``` sh
229264yarn test:examples
230265```
0 commit comments