release: 1.21.0 (#783)

stainless-app[bot] · web-flow · commit 788e18b43dff · 2026-05-13T09:03:32.000-07:00
Co-authored-by: stainless-app[bot] &lt;142633134+stainless-app[bot]@users.noreply.github.com&gt;
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "1.20.0"
+  ".": "1.21.0"
 }
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
-configured_endpoints: 115
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/runloop-ai%2Frunloop-406ebae7a9b8525a70a6400f4119209fc0230f73c93f56b63ee27b43cf7e5085.yml
-openapi_spec_hash: 7ad158db2a73b2a9c31fce2f7f8f935a
-config_hash: 12de9459ff629b6a3072a75b236b7b70
+configured_endpoints: 119
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/runloop-ai/runloop-40b78fbce4172c1fdab1559718cc9a7ba6b47402ee0bcb8dbefa582448958384.yml
+openapi_spec_hash: 78673375a4e58f7b4cea847ce2686b0e
+config_hash: 07d725fff578f22e8cb52e3c588f24c6
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.21.0 (2026-05-12)
+
+Full Changelog: [v1.20.0...v1.21.0](https://github.com/runloopai/api-client-ts/compare/v1.20.0...v1.21.0)
+
+### Features
+
+* make agent version optional in API ([#8858](https://github.com/runloopai/api-client-ts/issues/8858)) ([9676132](https://github.com/runloopai/api-client-ts/commit/9676132d3a4dd6ad458229a309349160832edd8a))
+* **metadata:** add object metadata viewing, discovery, and validation ([#9124](https://github.com/runloopai/api-client-ts/issues/9124)) ([204e2a9](https://github.com/runloopai/api-client-ts/commit/204e2a9c871c6ea895348a32f8b1ef734e2fc19b))
+* support setting headers via env ([7f226b0](https://github.com/runloopai/api-client-ts/commit/7f226b081e7a8b4221379fa4530a81887de124b7))
+
+
+### Bug Fixes
+
+* **test:** increase SDK maxRetries from 1 to 3 for smoketest resilience ([#786](https://github.com/runloopai/api-client-ts/issues/786)) ([c8b5448](https://github.com/runloopai/api-client-ts/commit/c8b5448bb00d7108deb50749969ee09d8bf511e8))
+* update openapi.stainless.yaml for PTY server methods ([#9218](https://github.com/runloopai/api-client-ts/issues/9218)) ([e72f504](https://github.com/runloopai/api-client-ts/commit/e72f5046b989fae45edadb6840c696d48900ec8d))
+
+
+### Chores
+
+* add get secret to stainless ([#7833](https://github.com/runloopai/api-client-ts/issues/7833)) ([3e8eee7](https://github.com/runloopai/api-client-ts/commit/3e8eee7a59d9bd6f08d2060bdeaf58bfb29d93b8))
+* **internal:** more robust bootstrap script ([c31aa86](https://github.com/runloopai/api-client-ts/commit/c31aa86ba3c30b13052b18a6e498e0be685cb0fa))
+* **tests:** bump steady to v0.22.1 ([620beac](https://github.com/runloopai/api-client-ts/commit/620beac7bde9bdf9ef84b4bd023f844be0b2c37f))
+
+
+### Documentation
+
+* add missing SDK operations to README ([#785](https://github.com/runloopai/api-client-ts/issues/785)) ([128b60b](https://github.com/runloopai/api-client-ts/commit/128b60b1b346a873083d1b238573e1af05e97008))
+
 ## 1.20.0 (2026-04-14)
 
 Full Changelog: [v1.19.0...v1.20.0](https://github.com/runloopai/api-client-ts/compare/v1.19.0...v1.20.0)
diff --git a/api.md b/api.md
@@ -168,6 +168,7 @@ Types:
 - <code><a href="./src/resources/devboxes/devboxes.ts">DevboxSnapshotListView</a></code>
 - <code><a href="./src/resources/devboxes/devboxes.ts">DevboxSnapshotView</a></code>
 - <code><a href="./src/resources/devboxes/devboxes.ts">DevboxView</a></code>
+- <code><a href="./src/resources/devboxes/devboxes.ts">PtyTunnelView</a></code>
 - <code><a href="./src/resources/devboxes/devboxes.ts">TunnelView</a></code>
 - <code><a href="./src/resources/devboxes/devboxes.ts">DevboxCreateSSHKeyResponse</a></code>
 - <code><a href="./src/resources/devboxes/devboxes.ts">DevboxDeleteDiskSnapshotResponse</a></code>
@@ -182,6 +183,7 @@ Methods:
 - <code title="get /v1/devboxes/{id}">client.devboxes.<a href="./src/resources/devboxes/devboxes.ts">retrieve</a>(id) -> DevboxView</code>
 - <code title="post /v1/devboxes/{id}">client.devboxes.<a href="./src/resources/devboxes/devboxes.ts">update</a>(id, { ...params }) -> DevboxView</code>
 - <code title="get /v1/devboxes">client.devboxes.<a href="./src/resources/devboxes/devboxes.ts">list</a>({ ...params }) -> DevboxViewsDevboxesCursorIDPage</code>
+- <code title="post /v1/devboxes/{id}/create_pty_tunnel">client.devboxes.<a href="./src/resources/devboxes/devboxes.ts">createPtyTunnel</a>(id) -> PtyTunnelView</code>
 - <code title="post /v1/devboxes/{id}/create_ssh_key">client.devboxes.<a href="./src/resources/devboxes/devboxes.ts">createSSHKey</a>(id) -> DevboxCreateSSHKeyResponse</code>
 - <code title="post /v1/devboxes/disk_snapshots/{id}/delete">client.devboxes.<a href="./src/resources/devboxes/devboxes.ts">deleteDiskSnapshot</a>(id) -> unknown</code>
 - <code title="post /v1/devboxes/{id}/download_file">client.devboxes.<a href="./src/resources/devboxes/devboxes.ts">downloadFile</a>(id, { ...params }) -> Response</code>
@@ -243,6 +245,19 @@ Methods:
 - <code title="get /v1/devboxes/{devbox_id}/executions/{execution_id}/stream_stderr_updates">client.devboxes.executions.<a href="./src/resources/devboxes/executions.ts">streamStderrUpdates</a>(devboxId, executionId, { ...params }) -> ExecutionUpdateChunk</code>
 - <code title="get /v1/devboxes/{devbox_id}/executions/{execution_id}/stream_stdout_updates">client.devboxes.executions.<a href="./src/resources/devboxes/executions.ts">streamStdoutUpdates</a>(devboxId, executionId, { ...params }) -> ExecutionUpdateChunk</code>
 
+# Pty
+
+Types:
+
+- <code><a href="./src/resources/pty.ts">PtyConnectView</a></code>
+- <code><a href="./src/resources/pty.ts">PtyControlParameters</a></code>
+- <code><a href="./src/resources/pty.ts">PtyControlResultView</a></code>
+
+Methods:
+
+- <code title="get /pty/{session_name}">client.pty.<a href="./src/resources/pty.ts">connect</a>(sessionName, { ...params }) -> PtyConnectView</code>
+- <code title="post /pty/{session_name}/control">client.pty.<a href="./src/resources/pty.ts">control</a>(sessionName, { ...params }) -> PtyControlResultView</code>
+
 # Scenarios
 
 Types:
@@ -330,6 +345,7 @@ Types:
 Methods:
 
 - <code title="post /v1/secrets">client.secrets.<a href="./src/resources/secrets.ts">create</a>({ ...params }) -> SecretView</code>
+- <code title="get /v1/secrets/{name}">client.secrets.<a href="./src/resources/secrets.ts">retrieve</a>(name) -> SecretView</code>
 - <code title="post /v1/secrets/{name}">client.secrets.<a href="./src/resources/secrets.ts">update</a>(name, { ...params }) -> SecretView</code>
 - <code title="get /v1/secrets">client.secrets.<a href="./src/resources/secrets.ts">list</a>({ ...params }) -> SecretListView</code>
 - <code title="post /v1/secrets/{name}/delete">client.secrets.<a href="./src/resources/secrets.ts">delete</a>(name) -> SecretView</code>
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@runloop/api-client",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "The official TypeScript library for the Runloop API",
   "author": "Runloop <support@runloop.ai>",
   "types": "dist/sdk.d.ts",
diff --git a/packages/mcp-server/manifest.json b/packages/mcp-server/manifest.json
@@ -1,7 +1,7 @@
 {
   "dxt_version": "0.2",
   "name": "@runloop/api-client-mcp",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "The official MCP Server for the Runloop API",
   "author": {
     "name": "Runloop",
diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@runloop/api-client-mcp",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "The official MCP Server for the Runloop API",
   "author": "Runloop <support@runloop.ai>",
   "types": "dist/index.d.ts",
diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts
@@ -16,7 +16,7 @@ export const newMcpServer = async (stainlessApiKey: string | undefined) =>
   new McpServer(
     {
       name: 'runloop_api_client_api',
-      version: '1.20.0',
+      version: '1.21.0',
     },
     {
       instructions: await getInstructions(stainlessApiKey),
diff --git a/scripts/bootstrap b/scripts/bootstrap
@@ -4,7 +4,7 @@ set -e
 
 cd "$(dirname "$0")/.."
 
-if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "$SKIP_BREW" != "1" ] && [ -t 0 ]; then
+if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "${SKIP_BREW:-}" != "1" ] && [ -t 0 ]; then
   brew bundle check >/dev/null 2>&1 || {
     echo -n "==> Install Homebrew dependencies? (y/N): "
     read -r response
diff --git a/scripts/mock b/scripts/mock
@@ -22,9 +22,9 @@ echo "==> Starting mock server with URL ${URL}"
 # Run steady mock on the given spec
 if [ "$1" == "--daemon" ]; then
   # Pre-install the package so the download doesn't eat into the startup timeout
-  npm exec --package=@stdy/cli@0.20.2 -- steady --version
+  npm exec --package=@stdy/cli@0.22.1 -- steady --version
 
-  npm exec --package=@stdy/cli@0.20.2 -- steady --host 127.0.0.1 -p 4010 --validator-query-array-format=comma --validator-form-array-format=comma --validator-query-object-format=brackets --validator-form-object-format=brackets "$URL" &> .stdy.log &
+  npm exec --package=@stdy/cli@0.22.1 -- steady --host 127.0.0.1 -p 4010 --validator-query-array-format=comma --validator-form-array-format=comma --validator-query-object-format=brackets --validator-form-object-format=brackets "$URL" &> .stdy.log &
 
   # Wait for server to come online via health endpoint (max 30s)
   echo -n "Waiting for server"
@@ -48,5 +48,5 @@ if [ "$1" == "--daemon" ]; then
 
   echo
 else
-  npm exec --package=@stdy/cli@0.20.2 -- steady --host 127.0.0.1 -p 4010 --validator-query-array-format=comma --validator-form-array-format=comma --validator-query-object-format=brackets --validator-form-object-format=brackets "$URL"
+  npm exec --package=@stdy/cli@0.22.1 -- steady --host 127.0.0.1 -p 4010 --validator-query-array-format=comma --validator-form-array-format=comma --validator-query-object-format=brackets --validator-form-object-format=brackets "$URL"
 fi
diff --git a/scripts/test b/scripts/test
@@ -60,7 +60,7 @@ elif ! steady_is_running ; then
   echo -e "To run the server, pass in the path or url of your OpenAPI"
   echo -e "spec to the steady command:"
   echo
-  echo -e "  \$ ${YELLOW}npm exec --package=@stdy/cli@0.20.2 -- steady path/to/your.openapi.yml --host 127.0.0.1 -p 4010 --validator-query-array-format=comma --validator-form-array-format=comma --validator-query-object-format=brackets --validator-form-object-format=brackets${NC}"
+  echo -e "  \$ ${YELLOW}npm exec --package=@stdy/cli@0.22.1 -- steady path/to/your.openapi.yml --host 127.0.0.1 -p 4010 --validator-query-array-format=comma --validator-form-array-format=comma --validator-query-object-format=brackets --validator-form-object-format=brackets${NC}"
   echo
 
   exit 1
diff --git a/src/index.ts b/src/index.ts
@@ -150,6 +150,14 @@ import {
   ObjectViewsObjectsCursorIDPage,
   Objects,
 } from './resources/objects';
+import {
+  Pty,
+  PtyConnectParams,
+  PtyConnectView,
+  PtyControlParameters,
+  PtyControlParams,
+  PtyControlResultView,
+} from './resources/pty';
 import {
   RestrictedKeyCreateParameters,
   RestrictedKeyCreateParams,
@@ -217,6 +225,7 @@ import {
   DevboxWaitForCommandParams,
   DevboxWriteFileContentsParams,
   Devboxes,
+  PtyTunnelView,
   TunnelView,
 } from './resources/devboxes/devboxes';
 import {
@@ -361,6 +370,18 @@ export class Runloop extends Core.APIClient {
       fetch: options.fetch,
     });
 
+    const customHeadersEnv = Core.readEnv('RUNLOOP_CUSTOM_HEADERS');
+    if (customHeadersEnv) {
+      const parsed: Record<string, string> = {};
+      for (const line of customHeadersEnv.split('\n')) {
+        const colon = line.indexOf(':');
+        if (colon >= 0) {
+          parsed[line.substring(0, colon).trim()] = line.substring(colon + 1).trim();
+        }
+      }
+      options.defaultHeaders = { ...parsed, ...options.defaultHeaders };
+    }
+
     this._options = options;
     this.idempotencyHeader = 'x-request-id';
 
@@ -374,6 +395,7 @@ export class Runloop extends Core.APIClient {
   axons: API.Axons = new API.Axons(this);
   blueprints: API.Blueprints = new API.Blueprints(this);
   devboxes: API.Devboxes = new API.Devboxes(this);
+  pty: API.Pty = new API.Pty(this);
   scenarios: API.Scenarios = new API.Scenarios(this);
   objects: API.Objects = new API.Objects(this);
   secrets: API.Secrets = new API.Secrets(this);
@@ -440,6 +462,7 @@ Runloop.BlueprintViewsBlueprintsCursorIDPage = BlueprintViewsBlueprintsCursorIDP
 Runloop.Devboxes = Devboxes;
 Runloop.DevboxViewsDevboxesCursorIDPage = DevboxViewsDevboxesCursorIDPage;
 Runloop.DevboxSnapshotViewsDiskSnapshotsCursorIDPage = DevboxSnapshotViewsDiskSnapshotsCursorIDPage;
+Runloop.Pty = Pty;
 Runloop.Scenarios = Scenarios;
 Runloop.ScenarioViewsScenariosCursorIDPage = ScenarioViewsScenariosCursorIDPage;
 Runloop.Objects = Objects;
@@ -635,6 +658,7 @@ export declare namespace Runloop {
     type DevboxSnapshotListView as DevboxSnapshotListView,
     type DevboxSnapshotView as DevboxSnapshotView,
     type DevboxView as DevboxView,
+    type PtyTunnelView as PtyTunnelView,
     type TunnelView as TunnelView,
     type DevboxCreateSSHKeyResponse as DevboxCreateSSHKeyResponse,
     type DevboxDeleteDiskSnapshotResponse as DevboxDeleteDiskSnapshotResponse,
@@ -662,6 +686,15 @@ export declare namespace Runloop {
     type DevboxWriteFileContentsParams as DevboxWriteFileContentsParams,
   };
 
+  export {
+    Pty as Pty,
+    type PtyConnectView as PtyConnectView,
+    type PtyControlParameters as PtyControlParameters,
+    type PtyControlResultView as PtyControlResultView,
+    type PtyConnectParams as PtyConnectParams,
+    type PtyControlParams as PtyControlParams,
+  };
+
   export {
     Scenarios as Scenarios,
     type InputContext as InputContext,
diff --git a/src/resources/agents.ts b/src/resources/agents.ts
@@ -90,14 +90,16 @@ export interface AgentCreateParameters {
   name: string;
 
   /**
-   * The version of the Agent. Must be a semver string (e.g., '2.0.65') or a SHA.
+   * The source configuration for the Agent.
    */
-  version: string;
+  source?: Shared.AgentSource | null;
 
   /**
-   * The source configuration for the Agent.
+   * Optional version identifier for the Agent. For npm/pip sources this is typically
+   * a semver string (e.g. '2.0.65'). For git sources it can be a branch or tag.
+   * Semantics are user-defined for object sources.
    */
-  source?: Shared.AgentSource | null;
+  version?: string | null;
 }
 
 /**
@@ -164,14 +166,16 @@ export interface AgentView {
   name: string;
 
   /**
-   * The version of the Agent. A semver string (e.g., '2.0.65') or a SHA.
+   * The source configuration for the Agent.
    */
-  version: string;
+  source?: Shared.AgentSource | null;
 
   /**
-   * The source configuration for the Agent.
+   * Optional version identifier for the Agent. For npm/pip sources this is typically
+   * a semver string (e.g. '2.0.65'). For git sources it can be a branch or tag.
+   * Omitted for object sources or when not provided.
    */
-  source?: Shared.AgentSource | null;
+  version?: string | null;
 }
 
 export type AgentDeleteResponse = unknown;
@@ -188,14 +192,16 @@ export interface AgentCreateParams {
   name: string;
 
   /**
-   * The version of the Agent. Must be a semver string (e.g., '2.0.65') or a SHA.
+   * The source configuration for the Agent.
    */
-  version: string;
+  source?: Shared.AgentSource | null;
 
   /**
-   * The source configuration for the Agent.
+   * Optional version identifier for the Agent. For npm/pip sources this is typically
+   * a semver string (e.g. '2.0.65'). For git sources it can be a branch or tag.
+   * Semantics are user-defined for object sources.
    */
-  source?: Shared.AgentSource | null;
+  version?: string | null;
 }
 
 export interface AgentListParams extends AgentsCursorIDPageParams {
diff --git a/src/resources/devboxes/devboxes.ts b/src/resources/devboxes/devboxes.ts
@@ -166,6 +166,16 @@ export class Devboxes extends APIResource {
     return this._client.getAPIList('/v1/devboxes', DevboxViewsDevboxesCursorIDPage, { query, ...options });
   }
 
+  /**
+   * Create an ephemeral authenticated tunnel for terminal access to a running
+   * Devbox. This tunnel is not persisted on the Devbox and is generated fresh on
+   * each request. The returned auth_token must be passed as a Bearer token in the
+   * Authorization header.
+   */
+  createPtyTunnel(id: string, options?: Core.RequestOptions): Core.APIPromise<PtyTunnelView> {
+    return this._client.post(`/v1/devboxes/${id}/create_pty_tunnel`, options);
+  }
+
   /**
    * Create an SSH key for a Devbox to enable remote access.
    */
@@ -964,6 +974,25 @@ export namespace DevboxView {
   }
 }
 
+/**
+ * An ephemeral PTY tunnel providing authenticated terminal access to a Devbox.
+ * These tunnels are not stored on the Devbox and are generated fresh on each
+ * request. Usage: https://{port}-{tunnel_key}.tunnel.runloop.ai with
+ * Authorization: Bearer {auth_token}
+ */
+export interface PtyTunnelView {
+  /**
+   * Bearer token for tunnel authentication. Always required for PTY tunnels.
+   */
+  auth_token: string;
+
+  /**
+   * The encrypted tunnel key used to construct the tunnel URL. URL format:
+   * https://{port}-{tunnel_key}.tunnel.runloop.{domain}
+   */
+  tunnel_key: string;
+}
+
 /**
  * A V2 tunnel provides secure HTTP access to services running on a Devbox. Tunnels
  * allow external clients to reach web servers, APIs, or other HTTP services
@@ -1497,6 +1526,7 @@ export declare namespace Devboxes {
     type DevboxSnapshotListView as DevboxSnapshotListView,
     type DevboxSnapshotView as DevboxSnapshotView,
     type DevboxView as DevboxView,
+    type PtyTunnelView as PtyTunnelView,
     type TunnelView as TunnelView,
     type DevboxCreateSSHKeyResponse as DevboxCreateSSHKeyResponse,
     type DevboxDeleteDiskSnapshotResponse as DevboxDeleteDiskSnapshotResponse,
diff --git a/src/resources/devboxes/index.ts b/src/resources/devboxes/index.ts
@@ -14,6 +14,7 @@ export {
   type DevboxSnapshotListView,
   type DevboxSnapshotView,
   type DevboxView,
+  type PtyTunnelView,
   type TunnelView,
   type DevboxCreateSSHKeyResponse,
   type DevboxDeleteDiskSnapshotResponse,
diff --git a/src/resources/index.ts b/src/resources/index.ts
@@ -97,6 +97,7 @@ export {
   type DevboxSnapshotListView,
   type DevboxSnapshotView,
   type DevboxView,
+  type PtyTunnelView,
   type TunnelView,
   type DevboxCreateSSHKeyResponse,
   type DevboxDeleteDiskSnapshotResponse,
@@ -171,6 +172,14 @@ export {
   type ObjectDownloadParams,
   type ObjectListPublicParams,
 } from './objects';
+export {
+  Pty,
+  type PtyConnectView,
+  type PtyControlParameters,
+  type PtyControlResultView,
+  type PtyConnectParams,
+  type PtyControlParams,
+} from './pty';
 export {
   RestrictedKeys,
   type RestrictedKeyCreatedView,
diff --git a/src/resources/objects.ts b/src/resources/objects.ts
diff --git a/src/resources/pty.ts b/src/resources/pty.ts
diff --git a/src/resources/secrets.ts b/src/resources/secrets.ts
diff --git a/src/version.ts b/src/version.ts
diff --git a/tests/api-resources/agents.test.ts b/tests/api-resources/agents.test.ts
diff --git a/tests/api-resources/devboxes/devboxes.test.ts b/tests/api-resources/devboxes/devboxes.test.ts
diff --git a/tests/api-resources/pty.test.ts b/tests/api-resources/pty.test.ts
diff --git a/tests/api-resources/secrets.test.ts b/tests/api-resources/secrets.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`{`
`2`		`- ".": "1.20.0"`
	`2`	`+ ".": "1.21.0"`
`3`	`3`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@runloop/api-client",`
`3`		`- "version": "1.20.0",`
	`3`	`+ "version": "1.21.0",`
`4`	`4`	`"description": "The official TypeScript library for the Runloop API",`
`5`	`5`	`"author": "Runloop <support@runloop.ai>",`
`6`	`6`	`"types": "dist/sdk.d.ts",`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"dxt_version": "0.2",`
`3`	`3`	`"name": "@runloop/api-client-mcp",`
`4`		`- "version": "1.20.0",`
	`4`	`+ "version": "1.21.0",`
`5`	`5`	`"description": "The official MCP Server for the Runloop API",`
`6`	`6`	`"author": {`
`7`	`7`	`"name": "Runloop",`
Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@ export const newMcpServer = async (stainlessApiKey: string \| undefined) =>`
`16`	`16`	`new McpServer(`
`17`	`17`	`{`
`18`	`18`	`name: 'runloop_api_client_api',`
`19`		`- version: '1.20.0',`
	`19`	`+ version: '1.21.0',`
`20`	`20`	`},`
`21`	`21`	`{`
`22`	`22`	`instructions: await getInstructions(stainlessApiKey),`