added agent gateway to secret example

Author: james-rl

EXAMPLES.md

@@ -12,7 +12,7 @@ Runnable examples live in [`examples/`](./examples).
 - [Devbox Snapshot and Resume](#devbox-snapshot-resume)
 - [Devbox Tunnel (HTTP Server Access)](#devbox-tunnel)
 - [MCP Hub + Claude Code + GitHub](#mcp-github-tools)
-- [Secrets with Devbox (Create, Inject, Verify, Delete)](#secrets-with-devbox)
+- [Secrets with Devbox via Agent Gateway](#secrets-with-devbox)
 
 <a id="blueprint-with-build-context"></a>
 ## Blueprint with Build Context
@@ -168,20 +168,18 @@ uv run pytest -m smoketest tests/smoketests/examples/
 **Source:** [`examples/mcp_github_tools.py`](./examples/mcp_github_tools.py)
 
 <a id="secrets-with-devbox"></a>
-## Secrets with Devbox (Create, Inject, Verify, Delete)
+## Secrets with Devbox via Agent Gateway
 
-**Use case:** Create a secret, inject it into a devbox as an environment variable, verify access, and clean up.
+**Use case:** Create a secret, proxy it into a devbox through agent gateway, verify the devbox only gets gateway credentials, and clean up.
 
-**Tags:** `secrets`, `devbox`, `environment-variables`, `cleanup`
+**Tags:** `secrets`, `devbox`, `agent-gateway`, `credentials`, `cleanup`
 
 ### Workflow
-- Create a secret with a test value
-- Create a devbox with the secret mapped to an env var
-- Execute a command that reads the secret from the environment
-- Verify the value matches
-- Update the secret and verify
-- List secrets and verify the secret appears
-- Shutdown devbox and delete secret
+- Create a secret with a test credential
+- Create an agent gateway config for an upstream API
+- Launch a devbox with the gateway wired to the secret
+- Verify the devbox receives a gateway URL and token instead of the raw secret
+- Shutdown the devbox and delete the gateway config and secret
 
 ### Prerequisites
 - `RUNLOOP_API_KEY`

examples/registry.py

@@ -55,7 +55,7 @@
     },
     {
         "slug": "secrets-with-devbox",
-        "title": "Secrets with Devbox (Create, Inject, Verify, Delete)",
+        "title": "Secrets with Devbox via Agent Gateway",
         "file_name": "secrets_with_devbox.py",
         "required_env": ["RUNLOOP_API_KEY"],
         "run": run_secrets_with_devbox_example,

examples/secrets_with_devbox.py

@@ -1,21 +1,20 @@
 #!/usr/bin/env -S uv run python
 """
 ---
-title: Secrets with Devbox (Create, Inject, Verify, Delete)
+title: Secrets with Devbox via Agent Gateway
 slug: secrets-with-devbox
-use_case: Create a secret, inject it into a devbox as an environment variable, verify access, and clean up.
+use_case: Create a secret, proxy it into a devbox through agent gateway, verify the devbox only gets gateway credentials, and clean up.
 workflow:
-  - Create a secret with a test value
-  - Create a devbox with the secret mapped to an env var
-  - Execute a command that reads the secret from the environment
-  - Verify the value matches
-  - Update the secret and verify
-  - List secrets and verify the secret appears
-  - Shutdown devbox and delete secret
+  - Create a secret with a test credential
+  - Create an agent gateway config for an upstream API
+  - Launch a devbox with the gateway wired to the secret
+  - Verify the devbox receives a gateway URL and token instead of the raw secret
+  - Shutdown the devbox and delete the gateway config and secret
 tags:
   - secrets
   - devbox
-  - environment-variables
+  - agent-gateway
+  - credentials
   - cleanup
 prerequisites:
   - RUNLOOP_API_KEY
@@ -33,19 +32,19 @@
 
 # Note: do NOT hardcode secret values in your code!
 # This is example code only; use environment variables instead!
-_EXAMPLE_SECRET_VALUE = "my-secret-value"
-_UPDATED_SECRET_VALUE = "updated-secret-value"
+_EXAMPLE_GATEWAY_ENDPOINT = "https://api.example.com"
+_EXAMPLE_SECRET_VALUE = "example-upstream-api-key"
 
 
 def recipe(ctx: RecipeContext) -> RecipeOutput:
-    """Create a secret, inject it into a devbox, and verify it is accessible."""
+    """Create a secret, proxy it through an agent gateway, and verify the devbox only gets gateway credentials."""
     cleanup = ctx.cleanup
 
     sdk = RunloopSDK()
     resources_created: list[str] = []
     checks: list[ExampleCheck] = []
 
-    secret_name = unique_name("RUNLOOP_SDK_EXAMPLE").upper().replace("-", "_")
+    secret_name = unique_name("agent-gateway-secret")
 
     secret = sdk.secret.create(name=secret_name, value=_EXAMPLE_SECRET_VALUE)
     resources_created.append(f"secret:{secret_name}")
@@ -60,10 +59,33 @@ def recipe(ctx: RecipeContext) -> RecipeOutput:
         )
     )
 
+    # Hide upstream credentials from the devbox by routing requests through an
+    # agent gateway config. This prevents direct secret exfiltration.
+    gateway_config = sdk.gateway_config.create(
+        name=unique_name("agent-gateway-config"),
+        endpoint=_EXAMPLE_GATEWAY_ENDPOINT,
+        auth_mechanism={"type": "bearer"},
+        description="Example gateway that keeps upstream credentials off the devbox",
+    )
+    resources_created.append(f"gateway_config:{gateway_config.id}")
+    cleanup.add(f"gateway_config:{gateway_config.id}", gateway_config.delete)
+
+    gateway_info = gateway_config.get_info()
+    checks.append(
+        ExampleCheck(
+            name="gateway config created successfully",
+            passed=(gateway_info.id.startswith("gwc_") and gateway_info.endpoint == _EXAMPLE_GATEWAY_ENDPOINT),
+            details=f"id={gateway_info.id}, endpoint={gateway_info.endpoint}",
+        )
+    )
+
     devbox = sdk.devbox.create(
-        name=unique_name("secrets-example-devbox"),
-        secrets={
-            "MY_SECRET_ENV": secret.name,
+        name=unique_name("agent-gateway-devbox"),
+        gateways={
+            "MY_API": {
+                "gateway": gateway_config.id,
+                "secret": secret.name,
+            }
         },
         launch_parameters={
             "resource_size_request": "X_SMALL",
@@ -73,32 +95,44 @@ def recipe(ctx: RecipeContext) -> RecipeOutput:
     resources_created.append(f"devbox:{devbox.id}")
     cleanup.add(f"devbox:{devbox.id}", devbox.shutdown)
 
-    result = devbox.cmd.exec("echo $MY_SECRET_ENV")
-    stdout = result.stdout().strip()
+    devbox_info = devbox.get_info()
     checks.append(
         ExampleCheck(
-            name="devbox can read secret as env var",
-            passed=result.exit_code == 0 and stdout == _EXAMPLE_SECRET_VALUE,
-            details=f'exit_code={result.exit_code}, stdout="{stdout}"',
+            name="devbox records gateway wiring",
+            passed=(
+                devbox_info.gateway_specs is not None
+                and devbox_info.gateway_specs.get("MY_API") is not None
+                and devbox_info.gateway_specs["MY_API"].gateway_config_id == gateway_config.id
+            ),
+            details=(
+                f"gateway_config_id={devbox_info.gateway_specs['MY_API'].gateway_config_id}"
+                if devbox_info.gateway_specs is not None and devbox_info.gateway_specs.get("MY_API") is not None
+                else "gateway spec missing"
+            ),
         )
     )
 
-    updated_info = sdk.secret.update(secret, _UPDATED_SECRET_VALUE).get_info()
+    url_result = devbox.cmd.exec("echo $MY_API_URL")
+    gateway_url = url_result.stdout().strip()
     checks.append(
         ExampleCheck(
-            name="secret updated successfully",
-            passed=updated_info.name == secret_name,
-            details=f"update_time_ms={updated_info.update_time_ms}",
+            name="devbox receives gateway URL",
+            passed=url_result.exit_code == 0 and gateway_url.startswith("http"),
+            details=f"exit_code={url_result.exit_code}, url={gateway_url}",
         )
     )
 
-    secrets = sdk.secret.list()
-    found = next((s for s in secrets if s.name == secret_name), None)
+    token_result = devbox.cmd.exec("echo $MY_API")
+    gateway_token = token_result.stdout().strip()
     checks.append(
         ExampleCheck(
-            name="secret appears in list",
-            passed=found is not None,
-            details=f"found name={found.name}" if found else "not found",
+            name="devbox receives gateway token instead of raw secret",
+            passed=(
+                token_result.exit_code == 0
+                and gateway_token.startswith("gws_")
+                and gateway_token != _EXAMPLE_SECRET_VALUE
+            ),
+            details=(f"exit_code={token_result.exit_code}, token_prefix={gateway_token[:4] or 'missing'}"),
         )
     )
 

llms.txt

@@ -13,7 +13,7 @@
 - [Devbox lifecycle example](examples/devbox_from_blueprint_lifecycle.py): Create blueprint, launch devbox, run commands, cleanup
 - [Devbox snapshot and resume example](examples/devbox_snapshot_resume.py): Snapshot disk, resume from snapshot, verify state isolation
 - [MCP GitHub example](examples/mcp_github_tools.py): MCP Hub integration with Claude Code
-- [Secrets with Devbox example](examples/secrets_with_devbox.py): Create secret, inject into devbox, verify, cleanup
+- [Secrets with Devbox example](examples/secrets_with_devbox.py): Create secret, protect it with agent gateway config, verify gateway credentials in devbox, cleanup
 
 ## API Reference