feat(sdk): added secrets as first class concepts and examples

EXAMPLES.md

@@ -9,6 +9,7 @@ Runnable examples live in [`examples/`](./examples).
 
 - [Devbox From Blueprint (Run Command, Shutdown)](#devbox-from-blueprint-lifecycle)
 - [MCP Hub + Claude Code + GitHub](#mcp-github-tools)
+- [Secrets with Devbox (Create, Inject, Verify, Delete)](#secrets-with-devbox)
 
 <a id="devbox-from-blueprint-lifecycle"></a>
 ## Devbox From Blueprint (Run Command, Shutdown)
@@ -70,3 +71,32 @@ yarn test:examples
 ```
 
 **Source:** [`examples/mcp-github-tools.ts`](./examples/mcp-github-tools.ts)
+
+<a id="secrets-with-devbox"></a>
+## Secrets with Devbox (Create, Inject, Verify, Delete)
+
+**Use case:** Create a secret, inject it into a devbox as an environment variable, verify access, and clean up.
+
+**Tags:** `secrets`, `devbox`, `environment-variables`, `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
+- Shutdown devbox and delete secret
+
+### Prerequisites
+- `RUNLOOP_API_KEY`
+
+### Run
+```sh
+yarn tsn -T examples/secrets-with-devbox.ts
+```
+
+### Test
+```sh
+yarn test:examples
+```
+
+**Source:** [`examples/secrets-with-devbox.ts`](./examples/secrets-with-devbox.ts)

README.md

@@ -79,6 +79,7 @@ The SDK provides object-oriented interfaces for all major Runloop resources:
 - **[`runloop.agent`](https://runloopai.github.io/api-client-ts/stable/classes/sdk.AgentOps.html)** - Agent management (create, list agents from npm/pip/git)
 - **[`runloop.scenario`](https://runloopai.github.io/api-client-ts/stable/classes/sdk.ScenarioOps.html)** - Scenario management (list scenarios, start runs)
 - **[`runloop.scorer`](https://runloopai.github.io/api-client-ts/stable/classes/sdk.ScorerOps.html)** - Scorer management (create, list, update)
+- **[`runloop.secret`](https://runloopai.github.io/api-client-ts/stable/classes/sdk.SecretOps.html)** - Secret management (create, update, list, delete encrypted key-value pairs)
 - **[`runloop.api`](https://runloopai.github.io/api-client-ts/stable/modules/types.html)** - Direct access to the REST API client
 
 ## TypeScript Support

examples/mcp-github-tools.ts

@@ -78,14 +78,13 @@ export async function recipe(ctx: RecipeContext, options: McpExampleOptions): Pr
   cleanup.add(`mcp_config:${mcpConfig.id}`, () => sdk.mcpConfig.fromId(mcpConfig.id).delete());
 
   // Store the GitHub PAT as a Runloop secret
-  // Note: secrets are currently available via sdk.api, not sdk.secret ops
-  const secretName = uniqueName('example-github-mcp');
-  await sdk.api.secrets.create({
+  const secretName = 'GITHUB_MCP_EXAMPLE';
+  const secret = await sdk.secret.create({
     name: secretName,
     value: githubToken,
   });
   resourcesCreated.push(`secret:${secretName}`);
-  cleanup.add(`secret:${secretName}`, () => sdk.api.secrets.delete(secretName));
+  cleanup.add(`secret:${secretName}`, () => secret.delete());
 
   // Launch a devbox with MCP Hub wiring
   const devbox = await sdk.devbox.create({
@@ -97,7 +96,7 @@ export async function recipe(ctx: RecipeContext, options: McpExampleOptions): Pr
     mcp: {
       MCP_SECRET: {
         mcp_config: mcpConfig.id,
-        secret: secretName,
+        secret: secret,
       },
     },
   });

examples/registry.ts

@@ -5,6 +5,7 @@
 import type { ExampleResult } from './types';
 import { runDevboxFromBlueprintLifecycleExample } from './devbox-from-blueprint-lifecycle';
 import { runMcpGithubToolsExample } from './mcp-github-tools';
+import { runSecretsWithDevboxExample } from './secrets-with-devbox';
 
 export interface ExampleRegistryEntry {
   slug: string;
@@ -29,4 +30,11 @@ export const exampleRegistry: ExampleRegistryEntry[] = [
     requiredEnv: ['RUNLOOP_API_KEY', 'GITHUB_TOKEN', 'ANTHROPIC_API_KEY'],
     run: runMcpGithubToolsExample,
   },
+  {
+    slug: 'secrets-with-devbox',
+    title: 'Secrets with Devbox (Create, Inject, Verify, Delete)',
+    fileName: 'secrets-with-devbox.ts',
+    requiredEnv: ['RUNLOOP_API_KEY'],
+    run: runSecretsWithDevboxExample,
+  },
 ];

examples/secrets-with-devbox.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env -S npm run tsn -T
+
+/**
+---
+title: Secrets with Devbox (Create, Inject, Verify, Delete)
+slug: secrets-with-devbox
+use_case: Create a secret, inject it into a devbox as an environment variable, verify access, 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
+  - Shutdown devbox and delete secret
+tags:
+  - secrets
+  - devbox
+  - environment-variables
+  - cleanup
+prerequisites:
+  - RUNLOOP_API_KEY
+run: yarn tsn -T examples/secrets-with-devbox.ts
+test: yarn test:examples
+---
+*/
+
+import { RunloopSDK } from '@runloop/api-client';
+import { wrapRecipe, runAsCli } from './_harness';
+import type { RecipeContext, RecipeOutput } from './types';
+
+export async function recipe(ctx: RecipeContext): Promise<RecipeOutput> {
+  const { cleanup } = ctx;
+
+  const sdk = new RunloopSDK({
+    bearerToken: process.env['RUNLOOP_API_KEY'],
+  });
+
+  const secretName = 'RUNLOOP_SECRET_EXAMPLE';
+  // Note: do NOT hardcode secret values in your code!
+  // this is example code only; use environment variables instead!
+  const secretValue = 'my-secret-value';
+
+  const secret = await sdk.secret.create({
+    name: secretName,
+    value: secretValue,
+  });
+  cleanup.add(`secret:${secretName}`, () => secret.delete());
+
+  const devbox = await sdk.devbox.create({
+    name: 'secrets-example-devbox',
+    secrets: {
+      MY_SECRET_ENV: secret,
+    },
+    launch_parameters: {
+      resource_size_request: 'X_SMALL',
+      keep_alive_time_seconds: 60 * 5,
+    },
+  });
+  cleanup.add(`devbox:${devbox.id}`, () => sdk.devbox.fromId(devbox.id).shutdown());
+
+  const result = await devbox.cmd.exec('echo $MY_SECRET_ENV');
+  const stdout = await result.stdout();
+
+  const updatedSecret = await sdk.secret.update(secret, {
+    value: 'updated-secret-value',
+  });
+
+  const secrets = await sdk.secret.list();
+  const foundSecret = secrets.find((s) => s.name === secretName);
+
+  const secretInfo = await secret.getInfo();
+  const updatedInfo = await updatedSecret.getInfo();
+
+  return {
+    resourcesCreated: [`secret:${secretName}`, `devbox:${devbox.id}`],
+    checks: [
+      {
+        name: 'secret created successfully',
+        passed: secret.name === secretName && secretInfo.id.startsWith('sec_'),
+        details: `name=${secret.name}, id=${secretInfo.id}`,
+      },
+      {
+        name: 'devbox can read secret as env var',
+        passed: result.exitCode === 0 && stdout.trim() === secretValue,
+        details: `exitCode=${result.exitCode}, stdout="${stdout.trim()}"`,
+      },
+      {
+        name: 'secret updated successfully',
+        passed: updatedSecret.name === secretName,
+        details: `update_time_ms=${updatedInfo.update_time_ms}`,
+      },
+      {
+        name: 'secret appears in list',
+        passed: foundSecret !== undefined && foundSecret.name === secretName,
+        details: foundSecret ? `found name=${foundSecret.name}` : 'not found',
+      },
+    ],
+  };
+}
+
+export const runSecretsWithDevboxExample = wrapRecipe({ recipe });
+
+if (require.main === module) {
+  void runAsCli(runSecretsWithDevboxExample);
+}

llms.txt

@@ -11,6 +11,7 @@
 
 - [Devbox lifecycle example](examples/devbox-from-blueprint-lifecycle.ts): Create blueprint, launch devbox, run commands, cleanup
 - [MCP GitHub example](examples/mcp-github-tools.ts): MCP Hub integration with Claude Code
+- [Secrets with Devbox example](examples/secrets-with-devbox.ts): Create secret, inject into devbox, verify, cleanup
 
 ## API Reference
 
@@ -21,7 +22,7 @@
 
 - Always use `RunloopSDK` as the entry point (not legacy `Runloop` default export)
 - Prefer SDK methods (`sdk.devbox`, `sdk.blueprint`, etc.) for object-oriented patterns and convenience
-- For resources without SDK coverage (e.g., secrets, benchmarks), use `sdk.api.*` as a fallback
+- For resources without SDK coverage (e.g., benchmarks), use `sdk.api.*` as a fallback
 - Use `sdk.devbox.create()` to create devboxes; they auto-await readiness
 - Use `devbox.cmd.exec('command')` for most commands—blocks until completion, returns `ExecutionResult` with stdout/stderr
 - Use `devbox.cmd.execAsync('command')` for long-running or background processes (servers, watchers)—returns immediately with `Execution` handle to check status, get result, or kill

src/resources/secrets.ts

@@ -13,6 +13,13 @@ export class Secrets extends APIResource {
     return this._client.post('/v1/secrets', { body, ...options });
   }
 
+  /**
+   * Retrieve a Secret by name.
+   */
+  retrieve(name: string, options?: Core.RequestOptions): Core.APIPromise<SecretView> {
+    return this._client.get(`/v1/secrets/${name}`, options);
+  }
+
   /**
    * Update the value of an existing Secret by name. The new value will be encrypted
    * at rest.