@alibaba-group/opensandbox 0.1.3-dev1 → 0.1.4

package/dist/{sandboxes-CLy12BN1.d.ts → sandboxes-Dc0G4ShU.d.ts}

@@ -169,11 +169,6 @@ interface ServerStreamEvent extends Record<string, unknown> {
     results?: Record<string, unknown>;
     error?: Record<string, unknown>;
 }
-interface RunCommandRequest extends Record<string, unknown> {
-    command: string;
-    cwd?: string;
-    background?: boolean;
-}
 interface CodeContextRequest extends Record<string, unknown> {
     language: string;
 }
@@ -187,6 +182,24 @@ interface RunCommandOpts {
      * Run command in detached mode.
      */
     background?: boolean;
+    /**
+     * Maximum execution time in seconds; server will terminate the command when reached.
+     * If omitted, the server will not enforce any timeout.
+     */
+    timeoutSeconds?: number;
+}
+interface CommandStatus {
+    id?: string;
+    content?: string;
+    running?: boolean;
+    exitCode?: number | null;
+    error?: string;
+    startedAt?: Date;
+    finishedAt?: Date | null;
+}
+interface CommandLogs {
+    content: string;
+    cursor?: number;
 }
 type CommandExecution = Execution;
 interface Metrics extends Record<string, unknown> {
@@ -223,6 +236,14 @@ interface ExecdCommands {
      * Note: Execd spec uses `DELETE /command?id=<sessionId>`.
      */
     interrupt(sessionId: string): Promise<void>;
+    /**
+     * Get the current running status for a command id.
+     */
+    getCommandStatus(commandId: string): Promise<CommandStatus>;
+    /**
+     * Get background command logs (non-streamed).
+     */
+    getBackgroundCommandLogs(commandId: string, cursor?: number): Promise<CommandLogs>;
 }
 
 interface ExecdHealth {
@@ -275,6 +296,64 @@ interface NetworkPolicy extends Record<string, unknown> {
      */
     egress?: NetworkRule[];
 }
+/**
+ * Host path bind mount backend.
+ *
+ * Maps a directory on the host filesystem into the container.
+ * Only available when the runtime supports host mounts.
+ */
+interface Host extends Record<string, unknown> {
+    /**
+     * Absolute path on the host filesystem to mount.
+     */
+    path: string;
+}
+/**
+ * Kubernetes PersistentVolumeClaim mount backend.
+ *
+ * References an existing PVC in the same namespace as the sandbox pod.
+ * Only available in Kubernetes runtime.
+ */
+interface PVC extends Record<string, unknown> {
+    /**
+     * Name of the PersistentVolumeClaim in the same namespace.
+     */
+    claimName: string;
+}
+/**
+ * Storage mount definition for a sandbox.
+ *
+ * Each volume entry contains:
+ * - A unique name identifier
+ * - Exactly one backend (host, pvc) with backend-specific fields
+ * - Common mount settings (mountPath, readOnly, subPath)
+ */
+interface Volume extends Record<string, unknown> {
+    /**
+     * Unique identifier for the volume within the sandbox.
+     */
+    name: string;
+    /**
+     * Host path bind mount backend (mutually exclusive with pvc).
+     */
+    host?: Host;
+    /**
+     * Kubernetes PVC mount backend (mutually exclusive with host).
+     */
+    pvc?: PVC;
+    /**
+     * Absolute path inside the container where the volume is mounted.
+     */
+    mountPath: string;
+    /**
+     * If true, the volume is mounted as read-only. Defaults to false (read-write).
+     */
+    readOnly?: boolean;
+    /**
+     * Optional subdirectory under the backend path to mount.
+     */
+    subPath?: string;
+}
 type SandboxState = "Creating" | "Running" | "Pausing" | "Paused" | "Resuming" | "Deleting" | "Deleted" | "Error" | string;
 interface SandboxStatus extends Record<string, unknown> {
     state: SandboxState;
@@ -310,6 +389,10 @@ interface CreateSandboxRequest extends Record<string, unknown> {
      * Optional outbound network policy for the sandbox.
      */
     networkPolicy?: NetworkPolicy;
+    /**
+     * Optional list of volume mounts for persistent storage.
+     */
+    volumes?: Volume[];
     extensions?: Record<string, unknown>;
 }
 interface CreateSandboxResponse extends Record<string, unknown> {
@@ -348,6 +431,11 @@ interface RenewSandboxExpirationResponse extends Record<string, unknown> {
 }
 interface Endpoint extends Record<string, unknown> {
     endpoint: string;
+    /**
+     * Headers that must be included on every request targeting this endpoint
+     * (e.g. when the server requires them for routing or auth). Omit or empty if not required.
+     */
+    headers?: Record<string, string>;
 }
 interface ListSandboxesParams {
     /**
@@ -372,7 +460,7 @@ interface Sandboxes {
     pauseSandbox(sandboxId: SandboxId): Promise<void>;
     resumeSandbox(sandboxId: SandboxId): Promise<void>;
     renewSandboxExpiration(sandboxId: SandboxId, req: RenewSandboxExpirationRequest): Promise<RenewSandboxExpirationResponse>;
-    getSandboxEndpoint(sandboxId: SandboxId, port: number): Promise<Endpoint>;
+    getSandboxEndpoint(sandboxId: SandboxId, port: number, useServerProxy?: boolean): Promise<Endpoint>;
 }
 
-export type { RenewSandboxExpirationRequest as A, ReplaceFileContentItem as B, CodeContextRequest as C, RunCommandOpts as D, ExecdCommands as E, FileInfo as F, RunCommandRequest as G, SearchEntry as H, SearchFilesResponse as I, SetPermissionEntry as J, SupportedLanguage as K, ListSandboxesResponse as L, Metrics as M, NetworkPolicy as N, OutputMessage as O, Permission as P, RenewSandboxExpirationResponse as R, Sandboxes as S, WriteEntry as W, SandboxFiles as a, ExecdHealth as b, ExecdMetrics as c, SandboxId as d, SandboxInfo as e, Execution as f, ExecutionHandlers as g, ServerStreamEvent as h, SandboxMetrics as i, Endpoint as j, CommandExecution as k, ContentReplaceEntry as l, CreateSandboxRequest as m, CreateSandboxResponse as n, ExecutionComplete as o, ExecutionError as p, ExecutionInit as q, ExecutionResult as r, FileMetadata as s, FilesInfoResponse as t, ListSandboxesParams as u, MoveEntry as v, NetworkRule as w, NetworkRuleAction as x, PingResponse as y, RenameFileItem as z };
+export type { Permission as A, PingResponse as B, CodeContextRequest as C, RenameFileItem as D, ExecdCommands as E, FileInfo as F, RenewSandboxExpirationRequest as G, Host as H, ReplaceFileContentItem as I, RunCommandOpts as J, SearchEntry as K, ListSandboxesResponse as L, Metrics as M, NetworkPolicy as N, OutputMessage as O, PVC as P, SearchFilesResponse as Q, RenewSandboxExpirationResponse as R, Sandboxes as S, SetPermissionEntry as T, SupportedLanguage as U, Volume as V, WriteEntry as W, SandboxFiles as a, ExecdHealth as b, ExecdMetrics as c, SandboxId as d, SandboxInfo as e, Execution as f, ExecutionHandlers as g, ServerStreamEvent as h, SandboxMetrics as i, Endpoint as j, CommandExecution as k, CommandLogs as l, CommandStatus as m, ContentReplaceEntry as n, CreateSandboxRequest as o, CreateSandboxResponse as p, ExecutionComplete as q, ExecutionError as r, ExecutionInit as s, ExecutionResult as t, FileMetadata as u, FilesInfoResponse as v, ListSandboxesParams as w, MoveEntry as x, NetworkRule as y, NetworkRuleAction as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alibaba-group/opensandbox",
-  "version": "0.1.3-dev1",
+  "version": "0.1.4",
   "description": "OpenSandbox TypeScript/JavaScript SDK (sandbox lifecycle + execd APIs)",
   "license": "Apache-2.0",
   "type": "module",

package/src/adapters/commandsAdapter.ts

@@ -16,7 +16,13 @@ import type { ExecdClient } from "../openapi/execdClient.js";
 import { throwOnOpenApiFetchError } from "./openapiError.js";
 import { parseJsonEventStream } from "./sse.js";
 import type { paths as ExecdPaths } from "../api/execd.js";
-import type { CommandExecution, RunCommandOpts, ServerStreamEvent } from "../models/execd.js";
+import type {
+  CommandExecution,
+  CommandLogs,
+  CommandStatus,
+  RunCommandOpts,
+  ServerStreamEvent,
+} from "../models/execd.js";
 import type { ExecdCommands } from "../services/execdCommands.js";
 import type { ExecutionHandlers } from "../models/execution.js";
 import { ExecutionEventDispatcher } from "../models/executionEventDispatcher.js";
@@ -29,13 +35,34 @@ function joinUrl(baseUrl: string, pathname: string): string {
 
 type ApiRunCommandRequest =
   ExecdPaths["/command"]["post"]["requestBody"]["content"]["application/json"];
+type ApiCommandStatusOk =
+  ExecdPaths["/command/status/{id}"]["get"]["responses"][200]["content"]["application/json"];
+type ApiCommandLogsOk =
+  ExecdPaths["/command/{id}/logs"]["get"]["responses"][200]["content"]["text/plain"];
 
 function toRunCommandRequest(command: string, opts?: RunCommandOpts): ApiRunCommandRequest {
-  return {
+  const body: ApiRunCommandRequest = {
     command,
     cwd: opts?.workingDirectory,
     background: !!opts?.background,
   };
+  if (opts?.timeoutSeconds != null) {
+    body.timeout = Math.round(opts.timeoutSeconds * 1000);
+  }
+  return body;
+}
+
+function parseOptionalDate(value: unknown, field: string): Date | undefined {
+  if (value == null) return undefined;
+  if (value instanceof Date) return value;
+  if (typeof value !== "string") {
+    throw new Error(`Invalid ${field}: expected ISO string, got ${typeof value}`);
+  }
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    throw new Error(`Invalid ${field}: ${value}`);
+  }
+  return parsed;
 }
 
 export interface CommandsAdapterOptions {
@@ -64,6 +91,44 @@ export class CommandsAdapter implements ExecdCommands {
     throwOnOpenApiFetchError({ error, response }, "Interrupt command failed");
   }
 
+  async getCommandStatus(commandId: string): Promise<CommandStatus> {
+    const { data, error, response } = await this.client.GET("/command/status/{id}", {
+      params: { path: { id: commandId } },
+    });
+    throwOnOpenApiFetchError({ error, response }, "Get command status failed");
+    const ok = data as ApiCommandStatusOk | undefined;
+    if (!ok || typeof ok !== "object") {
+      throw new Error("Get command status failed: unexpected response shape");
+    }
+    return {
+      id: ok.id,
+      content: ok.content,
+      running: ok.running,
+      exitCode: ok.exit_code ?? null,
+      error: ok.error,
+      startedAt: parseOptionalDate(ok.started_at, "startedAt"),
+      finishedAt: parseOptionalDate(ok.finished_at, "finishedAt") ?? null,
+    };
+  }
+
+  async getBackgroundCommandLogs(commandId: string, cursor?: number): Promise<CommandLogs> {
+    const { data, error, response } = await this.client.GET("/command/{id}/logs", {
+      params: { path: { id: commandId }, query: cursor == null ? {} : { cursor } },
+      parseAs: "text",
+    });
+    throwOnOpenApiFetchError({ error, response }, "Get command logs failed");
+    const ok = data as ApiCommandLogsOk | undefined;
+    if (typeof ok !== "string") {
+      throw new Error("Get command logs failed: unexpected response shape");
+    }
+    const cursorHeader = response.headers.get("EXECD-COMMANDS-TAIL-CURSOR");
+    const parsedCursor = (cursorHeader != null && cursorHeader !== "") ? Number(cursorHeader) : undefined;
+    return {
+      content: ok,
+      cursor: Number.isFinite(parsedCursor ?? NaN) ? parsedCursor : undefined,
+    };
+  }
+
   async *runStream(
     command: string,
     opts?: RunCommandOpts,

package/src/adapters/sandboxesAdapter.ts

@@ -173,9 +173,13 @@ export class SandboxesAdapter implements Sandboxes {
     } as RenewSandboxExpirationResponse;
   }
 
-  async getSandboxEndpoint(sandboxId: SandboxId, port: number): Promise<Endpoint> {
+  async getSandboxEndpoint(
+    sandboxId: SandboxId,
+    port: number,
+    useServerProxy = false
+  ): Promise<Endpoint> {
     const { data, error, response } = await this.client.GET("/sandboxes/{sandboxId}/endpoints/{port}", {
-      params: { path: { sandboxId, port } },
+      params: { path: { sandboxId, port }, query: { use_server_proxy: useServerProxy } },
     });
     throwOnOpenApiFetchError({ error, response }, "Get sandbox endpoint failed");
     const ok = data as ApiEndpointOk | undefined;

package/src/api/execd.ts

@@ -157,6 +157,8 @@ export interface paths {
          * @description Executes a shell command and streams the output in real-time using SSE (Server-Sent Events).
          *     The command can run in foreground or background mode. The response includes stdout, stderr,
          *     execution status, and completion events.
+         *     Optionally specify `timeout` (milliseconds) to enforce a maximum runtime; the server will
+         *     terminate the process when the timeout is reached.
          */
         post: operations["runCommand"];
         /**
@@ -519,6 +521,12 @@ export interface components {
              * @example false
              */
             background: boolean;
+            /**
+             * Format: int64
+             * @description Maximum allowed execution time in milliseconds before the command is forcefully terminated by the server. If omitted, the server will not enforce any timeout.
+             * @example 60000
+             */
+            timeout?: number;
         };
         /** @description Command execution status (foreground or background) */
         CommandStatusResponse: {

package/src/api/lifecycle.ts

@@ -394,7 +394,10 @@ export interface paths {
          */
         get: {
             parameters: {
-                query?: never;
+                query?: {
+                    /** @description Whether to return a server-proxied URL */
+                    use_server_proxy?: boolean;
+                };
                 header?: never;
                 path: {
                     /** @description Unique sandbox identifier */
@@ -642,6 +645,12 @@ export interface components {
              *     the sidecar starts in allow-all mode until updated.
              */
             networkPolicy?: components["schemas"]["NetworkPolicy"];
+            /**
+             * @description Storage mounts for the sandbox. Each volume entry specifies a named backend-specific
+             *     storage source and common mount settings. Exactly one backend type must be specified
+             *     per volume entry.
+             */
+            volumes?: components["schemas"]["Volume"][];
             /**
              * @description Opaque container for provider-specific or transient parameters not supported by the core API.
              *
@@ -715,6 +724,10 @@ export interface components {
              *     Example: endpoint.opensandbox.io/sandboxes/abc123/port/8080
              */
             endpoint: string;
+            /** @description Requests targeting the sandbox must include the corresponding header(s). */
+            headers?: {
+                [key: string]: string;
+            };
         };
         /**
          * @description Egress network policy matching the sidecar `/policy` request body.
@@ -742,6 +755,63 @@ export interface components {
              */
             target: string;
         };
+        /**
+         * @description Storage mount definition for a sandbox. Each volume entry contains:
+         *     - A unique name identifier
+         *     - Exactly one backend struct (host, pvc, etc.) with backend-specific fields
+         *     - Common mount settings (mountPath, readOnly, subPath)
+         */
+        Volume: {
+            /**
+             * @description Unique identifier for the volume within the sandbox.
+             *     Must be a valid DNS label (lowercase alphanumeric, hyphens allowed, max 63 chars).
+             */
+            name: string;
+            host?: components["schemas"]["Host"];
+            pvc?: components["schemas"]["PVC"];
+            /**
+             * @description Absolute path inside the container where the volume is mounted.
+             *     Must start with '/'.
+             */
+            mountPath: string;
+            /**
+             * @description If true, the volume is mounted as read-only. Defaults to false (read-write).
+             * @default false
+             */
+            readOnly: boolean;
+            /**
+             * @description Optional subdirectory under the backend path to mount.
+             *     Must be a relative path without '..' components.
+             */
+            subPath?: string;
+        };
+        /**
+         * @description Host path bind mount backend. Maps a directory on the host filesystem
+         *     into the container. Only available when the runtime supports host mounts.
+         *
+         *     Security note: Host paths are restricted by server-side allowlist.
+         *     Users must specify paths under permitted prefixes.
+         */
+        Host: {
+            /**
+             * @description Absolute path on the host filesystem to mount.
+             *     Must start with '/' and be under an allowed prefix.
+             */
+            path: string;
+        };
+        /**
+         * @description Kubernetes PersistentVolumeClaim mount backend. References an existing
+         *     PVC in the same namespace as the sandbox pod.
+         *
+         *     Only available in Kubernetes runtime.
+         */
+        PVC: {
+            /**
+             * @description Name of the PersistentVolumeClaim in the same namespace.
+             *     Must be a valid Kubernetes resource name.
+             */
+            claimName: string;
+        };
     };
     responses: {
         /** @description Error response envelope */

package/src/config/connection.ts

@@ -45,6 +45,11 @@ export interface ConnectionConfigOptions {
    * Enable basic debug logging for HTTP requests (best-effort).
    */
   debug?: boolean;
+  /**
+   * Use sandbox server as proxy for process execd requests.
+   * Useful when the client SDK cannot access the created sandbox directly.
+   */
+  useServerProxy?: boolean;
 }
 
 function isNodeRuntime(): boolean {
@@ -253,6 +258,10 @@ export class ConnectionConfig {
   readonly requestTimeoutSeconds: number;
   readonly debug: boolean;
   readonly userAgent: string = DEFAULT_USER_AGENT;
+  /**
+   * Use sandbox server as proxy for endpoint requests (default false).
+   */
+  readonly useServerProxy: boolean;
   private _closeTransport: () => Promise<void>;
   private _closePromise: Promise<void> | null = null;
   private _transportInitialized = false;
@@ -280,6 +289,7 @@ export class ConnectionConfig {
         ? opts.requestTimeoutSeconds
         : 30;
     this.debug = !!opts.debug;
+    this.useServerProxy = !!opts.useServerProxy;
 
     const headers: Record<string, string> = { ...(opts.headers ?? {}) };
     // Attach API key via header unless the user already provided one.
@@ -363,6 +373,7 @@ export class ConnectionConfig {
       headers: { ...this.headers },
       requestTimeoutSeconds: this.requestTimeoutSeconds,
       debug: this.debug,
+      useServerProxy: this.useServerProxy,
     });
     clone.initializeTransport();
     return clone;

package/src/core/constants.ts

@@ -26,4 +26,4 @@ export const DEFAULT_READY_TIMEOUT_SECONDS = 30;
 export const DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS = 200;
 
 export const DEFAULT_REQUEST_TIMEOUT_SECONDS = 30;
-export const DEFAULT_USER_AGENT = "OpenSandbox-JS-SDK/0.1.1";
+export const DEFAULT_USER_AGENT = "OpenSandbox-JS-SDK/0.1.4";

package/src/factory/adapterFactory.ts

@@ -31,6 +31,7 @@ export interface LifecycleStack {
 export interface CreateExecdStackOptions {
   connectionConfig: ConnectionConfig;
   execdBaseUrl: string;
+  endpointHeaders?: Record<string, string>;
 }
 
 export interface ExecdStack {

package/src/factory/defaultAdapterFactory.ts

@@ -36,9 +36,13 @@ export class DefaultAdapterFactory implements AdapterFactory {
   }
 
   createExecdStack(opts: CreateExecdStackOptions): ExecdStack {
+    const headers: Record<string, string> = {
+      ...(opts.connectionConfig.headers ?? {}),
+      ...(opts.endpointHeaders ?? {}),
+    };
     const execdClient = createExecdClient({
       baseUrl: opts.execdBaseUrl,
-      headers: opts.connectionConfig.headers,
+      headers,
       fetch: opts.connectionConfig.fetch,
     });
 
@@ -47,12 +51,12 @@ export class DefaultAdapterFactory implements AdapterFactory {
     const files = new FilesystemAdapter(execdClient, {
       baseUrl: opts.execdBaseUrl,
       fetch: opts.connectionConfig.fetch,
-      headers: opts.connectionConfig.headers,
+      headers,
     });
     const commands = new CommandsAdapter(execdClient, {
       baseUrl: opts.execdBaseUrl,
       fetch: opts.connectionConfig.sseFetch,
-      headers: opts.connectionConfig.headers,
+      headers,
     });
 
     return {

package/src/index.ts

@@ -33,15 +33,18 @@ export type {
   CreateSandboxRequest,
   CreateSandboxResponse,
   Endpoint,
+  Host,
   ListSandboxesParams,
   ListSandboxesResponse,
   NetworkPolicy,
   NetworkRule,
   NetworkRuleAction,
+  PVC,
   RenewSandboxExpirationRequest,
   RenewSandboxExpirationResponse,
   SandboxId,
   SandboxInfo,
+  Volume,
 } from "./models/sandboxes.js";
 
 export type { Sandboxes } from "./services/sandboxes.js";
@@ -63,8 +66,9 @@ export type {
 
 export type {
   CommandExecution,
+  CommandLogs,
+  CommandStatus,
   RunCommandOpts,
-  RunCommandRequest,
   ServerStreamEvent,
   CodeContextRequest,
   SupportedLanguage,

package/src/models/execd.ts

@@ -37,12 +37,6 @@ export interface ServerStreamEvent extends Record<string, unknown> {
   error?: Record<string, unknown>;
 }
 
-export interface RunCommandRequest extends Record<string, unknown> {
-  command: string;
-  cwd?: string;
-  background?: boolean;
-}
-
 export interface CodeContextRequest extends Record<string, unknown> {
   language: string;
 }
@@ -64,6 +58,26 @@ export interface RunCommandOpts {
    * Run command in detached mode.
    */
   background?: boolean;
+  /**
+   * Maximum execution time in seconds; server will terminate the command when reached.
+   * If omitted, the server will not enforce any timeout.
+   */
+  timeoutSeconds?: number;
+}
+
+export interface CommandStatus {
+  id?: string;
+  content?: string;
+  running?: boolean;
+  exitCode?: number | null;
+  error?: string;
+  startedAt?: Date;
+  finishedAt?: Date | null;
+}
+
+export interface CommandLogs {
+  content: string;
+  cursor?: number;
 }
 
 export type CommandExecution = Execution;

package/src/models/sandboxes.ts

@@ -62,6 +62,71 @@ export interface NetworkPolicy extends Record<string, unknown> {
   egress?: NetworkRule[];
 }
 
+// ============================================================================
+// Volume Models
+// ============================================================================
+
+/**
+ * Host path bind mount backend.
+ *
+ * Maps a directory on the host filesystem into the container.
+ * Only available when the runtime supports host mounts.
+ */
+export interface Host extends Record<string, unknown> {
+  /**
+   * Absolute path on the host filesystem to mount.
+   */
+  path: string;
+}
+
+/**
+ * Kubernetes PersistentVolumeClaim mount backend.
+ *
+ * References an existing PVC in the same namespace as the sandbox pod.
+ * Only available in Kubernetes runtime.
+ */
+export interface PVC extends Record<string, unknown> {
+  /**
+   * Name of the PersistentVolumeClaim in the same namespace.
+   */
+  claimName: string;
+}
+
+/**
+ * Storage mount definition for a sandbox.
+ *
+ * Each volume entry contains:
+ * - A unique name identifier
+ * - Exactly one backend (host, pvc) with backend-specific fields
+ * - Common mount settings (mountPath, readOnly, subPath)
+ */
+export interface Volume extends Record<string, unknown> {
+  /**
+   * Unique identifier for the volume within the sandbox.
+   */
+  name: string;
+  /**
+   * Host path bind mount backend (mutually exclusive with pvc).
+   */
+  host?: Host;
+  /**
+   * Kubernetes PVC mount backend (mutually exclusive with host).
+   */
+  pvc?: PVC;
+  /**
+   * Absolute path inside the container where the volume is mounted.
+   */
+  mountPath: string;
+  /**
+   * If true, the volume is mounted as read-only. Defaults to false (read-write).
+   */
+  readOnly?: boolean;
+  /**
+   * Optional subdirectory under the backend path to mount.
+   */
+  subPath?: string;
+}
+
 export type SandboxState =
   | "Creating"
   | "Running"
@@ -109,6 +174,10 @@ export interface CreateSandboxRequest extends Record<string, unknown> {
    * Optional outbound network policy for the sandbox.
    */
   networkPolicy?: NetworkPolicy;
+  /**
+   * Optional list of volume mounts for persistent storage.
+   */
+  volumes?: Volume[];
   extensions?: Record<string, unknown>;
 }
 
@@ -153,6 +222,11 @@ export interface RenewSandboxExpirationResponse extends Record<string, unknown>
 
 export interface Endpoint extends Record<string, unknown> {
   endpoint: string;
+  /**
+   * Headers that must be included on every request targeting this endpoint
+   * (e.g. when the server requires them for routing or auth). Omit or empty if not required.
+   */
+  headers?: Record<string, string>;
 }
 
 export interface ListSandboxesParams {