@alibaba-group/opensandbox 0.1.3 → 0.1.5

package/src/index.ts

@@ -33,15 +33,19 @@ export type {
   CreateSandboxRequest,
   CreateSandboxResponse,
   Endpoint,
+  Host,
   ListSandboxesParams,
   ListSandboxesResponse,
   NetworkPolicy,
   NetworkRule,
   NetworkRuleAction,
+  OSSFS,
+  PVC,
   RenewSandboxExpirationRequest,
   RenewSandboxExpirationResponse,
   SandboxId,
   SandboxInfo,
+  Volume,
 } from "./models/sandboxes.js";
 
 export type { Sandboxes } from "./services/sandboxes.js";
@@ -63,8 +67,9 @@ export type {
 
 export type {
   CommandExecution,
+  CommandLogs,
+  CommandStatus,
   RunCommandOpts,
-  RunCommandRequest,
   ServerStreamEvent,
   CodeContextRequest,
   SupportedLanguage,
@@ -87,6 +92,7 @@ export { ExecutionEventDispatcher } from "./models/executionEventDispatcher.js";
 
 export {
   DEFAULT_ENTRYPOINT,
+  DEFAULT_EGRESS_PORT,
   DEFAULT_EXECD_PORT,
   DEFAULT_RESOURCE_LIMITS,
   DEFAULT_TIMEOUT_SECONDS,
@@ -108,4 +114,4 @@ export type {
   SetPermissionEntry,
   WriteEntry,
 } from "./models/filesystem.js";
-export type { SandboxFiles } from "./services/filesystem.js";
+export type { SandboxFiles } from "./services/filesystem.js";

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,38 @@ 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;
+  /**
+   * Unix user ID used to run the command process.
+   */
+  uid?: number;
+  /**
+   * Unix group ID used to run the command process. Requires `uid`.
+   */
+  gid?: number;
+  /**
+   * Environment variables injected into the command process.
+   */
+  envs?: Record<string, string>;
+}
+
+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/execution.ts

@@ -54,6 +54,7 @@ export interface Execution {
   result: ExecutionResult[];
   error?: ExecutionError;
   complete?: ExecutionComplete;
+  exitCode?: number | null;
 }
 
 export interface ExecutionHandlers {
@@ -68,4 +69,4 @@ export interface ExecutionHandlers {
   onExecutionComplete?: (c: ExecutionComplete) => void | Promise<void>;
   onError?: (err: ExecutionError) => void | Promise<void>;
   onInit?: (init: ExecutionInit) => void | Promise<void>;
-}
+}

package/src/models/sandboxes.ts

@@ -62,6 +62,114 @@ 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;
+}
+
+/**
+ * Alibaba Cloud OSS mount backend via ossfs.
+ *
+ * The runtime mounts a host-side OSS path under `storage.ossfs_mount_root`
+ * so the container sees the bucket contents at the specified mount path.
+ *
+ * In Docker runtime, OSSFS backend requires OpenSandbox Server to run on a Linux host with FUSE support.
+ */
+export interface OSSFS extends Record<string, unknown> {
+  /**
+   * OSS bucket name.
+   */
+  bucket: string;
+  /**
+   * OSS endpoint (e.g., "oss-cn-hangzhou.aliyuncs.com").
+   */
+  endpoint: string;
+  /**
+   * ossfs major version used by runtime mount integration.
+   * @default "2.0"
+   */
+  version?: "1.0" | "2.0";
+  /**
+   * Additional ossfs mount options.
+   *
+   * - `1.0`: mounts with `ossfs ... -o <option>`
+   * - `2.0`: mounts with `ossfs2 mount ... -c <config-file>` and encodes options as `--<option>` lines in the config file
+   */
+  options?: string[];
+  /**
+   * OSS access key ID for inline credentials mode.
+   */
+  accessKeyId: string;
+  /**
+   * OSS access key secret for inline credentials mode.
+   */
+  accessKeySecret: string;
+}
+
+/**
+ * Storage mount definition for a sandbox.
+ *
+ * Each volume entry contains:
+ * - A unique name identifier
+ * - Exactly one backend (host, pvc, ossfs) 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, ossfs).
+   */
+  host?: Host;
+  /**
+   * Kubernetes PVC mount backend (mutually exclusive with host, ossfs).
+   */
+  pvc?: PVC;
+  /**
+   * Alibaba Cloud OSSFS mount backend (mutually exclusive with host, pvc).
+   */
+  ossfs?: OSSFS;
+  /**
+   * 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"
@@ -92,7 +200,7 @@ export interface SandboxInfo extends Record<string, unknown> {
   /**
    * Sandbox expiration time (server-side TTL).
    */
-  expiresAt: Date;
+  expiresAt: Date | null;
 }
 
 export interface CreateSandboxRequest extends Record<string, unknown> {
@@ -101,7 +209,7 @@ export interface CreateSandboxRequest extends Record<string, unknown> {
   /**
    * Timeout in seconds (server semantics).
    */
-  timeout: number;
+  timeout?: number | null;
   resourceLimits: ResourceLimits;
   env?: Record<string, string>;
   metadata?: Record<string, string>;
@@ -109,6 +217,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>;
 }
 
@@ -119,7 +231,7 @@ export interface CreateSandboxResponse extends Record<string, unknown> {
   /**
    * Sandbox expiration time after creation.
    */
-  expiresAt: Date;
+  expiresAt: Date | null;
   /**
    * Sandbox creation time.
    */
@@ -153,6 +265,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 {
@@ -168,4 +285,4 @@ export interface ListSandboxesParams {
   metadata?: Record<string, string>;
   page?: number;
   pageSize?: number;
-};
+};

package/src/openapi/egressClient.ts

@@ -0,0 +1,45 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import createClient from "openapi-fetch";
+import type { Client } from "openapi-fetch";
+
+import type { paths as EgressPaths } from "../api/egress.js";
+
+export type EgressClient = Client<EgressPaths>;
+
+export interface CreateEgressClientOptions {
+  /**
+   * Base URL to the sandbox egress sidecar API.
+   */
+  baseUrl: string;
+  /**
+   * Extra headers applied to every request.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Custom fetch implementation.
+   */
+  fetch?: typeof fetch;
+}
+
+export function createEgressClient(opts: CreateEgressClientOptions): EgressClient {
+  const createClientFn =
+    (createClient as unknown as { default?: typeof createClient }).default ?? createClient;
+  return createClientFn<EgressPaths>({
+    baseUrl: opts.baseUrl,
+    headers: opts.headers,
+    fetch: opts.fetch,
+  });
+}

package/src/sandbox.ts

@@ -14,6 +14,7 @@
 
 import {
   DEFAULT_ENTRYPOINT,
+  DEFAULT_EGRESS_PORT,
   DEFAULT_EXECD_PORT,
   DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS,
   DEFAULT_READY_TIMEOUT_SECONDS,
@@ -22,6 +23,7 @@ import {
 } from "./core/constants.js";
 import { ConnectionConfig, type ConnectionConfigOptions } from "./config/connection.js";
 import type { SandboxFiles } from "./services/filesystem.js";
+import type { Egress } from "./services/egress.js";
 import { createDefaultAdapterFactory } from "./factory/defaultAdapterFactory.js";
 import type { AdapterFactory } from "./factory/adapterFactory.js";
 
@@ -33,9 +35,11 @@ import type {
   CreateSandboxRequest,
   Endpoint,
   NetworkPolicy,
+  NetworkRule,
   RenewSandboxExpirationResponse,
   SandboxId,
   SandboxInfo,
+  Volume,
 } from "./models/sandboxes.js";
 import { SandboxReadyTimeoutException } from "./core/exceptions.js";
 
@@ -73,6 +77,11 @@ export interface SandboxCreateOptions {
    * If provided without defaultAction, defaults to "deny".
    */
   networkPolicy?: NetworkPolicy;
+  /**
+   * Optional list of volume mounts for persistent storage.
+   * Each volume specifies a backend (host path or PVC) and mount configuration.
+   */
+  volumes?: Volume[];
   /**
    * Opaque extension parameters passed through to the server as-is.
    */
@@ -85,9 +94,9 @@ export interface SandboxCreateOptions {
    */
   resource?: Record<string, string>;
   /**
-   * Sandbox timeout in seconds.
+   * Sandbox timeout in seconds. Set to `null` to require explicit cleanup.
    */
-  timeoutSeconds?: number;
+  timeoutSeconds?: number | null;
 
   /**
    * Skip readiness checks during create/connect.
@@ -181,6 +190,7 @@ export class Sandbox {
       adapterFactory: AdapterFactory;
       lifecycleBaseUrl: string;
       execdBaseUrl: string;
+      egress: Egress;
     }
   >();
 
@@ -195,6 +205,7 @@ export class Sandbox {
     files: SandboxFiles;
     health: ExecdHealth;
     metrics: ExecdMetrics;
+    egress: Egress;
   }) {
     this.id = opts.id;
     this.connectionConfig = opts.connectionConfig;
@@ -202,6 +213,7 @@ export class Sandbox {
       adapterFactory: opts.adapterFactory,
       lifecycleBaseUrl: opts.lifecycleBaseUrl,
       execdBaseUrl: opts.execdBaseUrl,
+      egress: opts.egress,
     });
 
     this.sandboxes = opts.sandboxes;
@@ -231,10 +243,37 @@ export class Sandbox {
       throw err;
     }
 
+    // Validate volumes: exactly one backend must be specified per volume
+    if (opts.volumes) {
+      for (const vol of opts.volumes) {
+        const backendsSpecified = [vol.host, vol.pvc, vol.ossfs].filter((b) => b != null).length;
+        if (backendsSpecified === 0) {
+          throw new Error(
+            `Volume '${vol.name}' must specify exactly one backend (host, pvc, ossfs), but none was provided.`
+          );
+        }
+        if (backendsSpecified > 1) {
+          throw new Error(
+            `Volume '${vol.name}' must specify exactly one backend (host, pvc, ossfs), but multiple were provided.`
+          );
+        }
+      }
+    }
+
+    const rawTimeout = opts.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
+    const timeoutSeconds =
+      opts.timeoutSeconds === null
+        ? null
+        : Math.floor(rawTimeout);
+    if (timeoutSeconds !== null && !Number.isFinite(timeoutSeconds)) {
+      throw new Error(
+        `timeoutSeconds must be a finite number, got ${opts.timeoutSeconds}`
+      );
+    }
+
     const req: CreateSandboxRequest = {
       image: toImageSpec(opts.image),
       entrypoint: opts.entrypoint ?? DEFAULT_ENTRYPOINT,
-      timeout: Math.floor(opts.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS),
       resourceLimits: opts.resource ?? DEFAULT_RESOURCE_LIMITS,
       env: opts.env ?? {},
       metadata: opts.metadata ?? {},
@@ -244,8 +283,12 @@ export class Sandbox {
             defaultAction: opts.networkPolicy.defaultAction ?? "deny",
           }
         : undefined,
+      volumes: opts.volumes,
       extensions: opts.extensions ?? {},
     };
+    if (timeoutSeconds !== null) {
+      req.timeout = timeoutSeconds;
+    }
 
     let sandboxId: SandboxId | undefined;
     try {
@@ -254,15 +297,28 @@ export class Sandbox {
 
       const endpoint = await sandboxes.getSandboxEndpoint(
         sandboxId,
-        DEFAULT_EXECD_PORT
+        DEFAULT_EXECD_PORT,
+        connectionConfig.useServerProxy
+      );
+      const egressEndpoint = await sandboxes.getSandboxEndpoint(
+        sandboxId,
+        DEFAULT_EGRESS_PORT,
+        connectionConfig.useServerProxy
       );
       const execdBaseUrl = `${connectionConfig.protocol}://${endpoint.endpoint}`;
+      const egressBaseUrl = `${connectionConfig.protocol}://${egressEndpoint.endpoint}`;
 
       const { commands, files, health, metrics } =
         adapterFactory.createExecdStack({
           connectionConfig,
           execdBaseUrl,
+          endpointHeaders: endpoint.headers,
         });
+      const { egress } = adapterFactory.createEgressStack({
+        connectionConfig,
+        egressBaseUrl,
+        endpointHeaders: egressEndpoint.headers,
+      });
 
       const sbx = new Sandbox({
         id: sandboxId,
@@ -275,6 +331,7 @@ export class Sandbox {
         files,
         health,
         metrics,
+        egress,
       });
 
       if (!(opts.skipHealthCheck ?? false)) {
@@ -325,14 +382,27 @@ export class Sandbox {
     try {
       const endpoint = await sandboxes.getSandboxEndpoint(
         opts.sandboxId,
-        DEFAULT_EXECD_PORT
+        DEFAULT_EXECD_PORT,
+        connectionConfig.useServerProxy
+      );
+      const egressEndpoint = await sandboxes.getSandboxEndpoint(
+        opts.sandboxId,
+        DEFAULT_EGRESS_PORT,
+        connectionConfig.useServerProxy
       );
       const execdBaseUrl = `${connectionConfig.protocol}://${endpoint.endpoint}`;
+      const egressBaseUrl = `${connectionConfig.protocol}://${egressEndpoint.endpoint}`;
       const { commands, files, health, metrics } =
         adapterFactory.createExecdStack({
           connectionConfig,
           execdBaseUrl,
+          endpointHeaders: endpoint.headers,
         });
+      const { egress } = adapterFactory.createEgressStack({
+        connectionConfig,
+        egressBaseUrl,
+        endpointHeaders: egressEndpoint.headers,
+      });
 
       const sbx = new Sandbox({
         id: opts.sandboxId,
@@ -345,6 +415,7 @@ export class Sandbox {
         files,
         health,
         metrics,
+        egress,
       });
 
       if (!(opts.skipHealthCheck ?? false)) {
@@ -458,11 +529,23 @@ export class Sandbox {
     return await this.sandboxes.renewSandboxExpiration(this.id, { expiresAt });
   }
 
+  async getEgressPolicy(): Promise<NetworkPolicy> {
+    return await Sandbox._priv.get(this)!.egress.getPolicy();
+  }
+
+  async patchEgressRules(rules: NetworkRule[]): Promise<void> {
+    await Sandbox._priv.get(this)!.egress.patchRules(rules);
+  }
+
   /**
    * Get sandbox endpoint for a port (STRICT: no scheme), e.g. "localhost:44772" or "domain/route/.../44772".
    */
   async getEndpoint(port: number): Promise<Endpoint> {
-    return await this.sandboxes.getSandboxEndpoint(this.id, port);
+    return await this.sandboxes.getSandboxEndpoint(
+      this.id,
+      port,
+      this.connectionConfig.useServerProxy
+    );
   }
 
   /**
@@ -479,26 +562,45 @@ export class Sandbox {
     healthCheck?: (sbx: Sandbox) => boolean | Promise<boolean>;
   }): Promise<void> {
     const deadline = Date.now() + opts.readyTimeoutSeconds * 1000;
+    let attempt = 0;
+    let errorDetail = "Health check returned false continuously.";
+
+    const buildTimeoutMessage = () => {
+      const context = `domain=${this.connectionConfig.domain}, useServerProxy=${this.connectionConfig.useServerProxy}`;
+      let suggestion =
+        "If this sandbox runs in Docker bridge or remote-network mode, consider enabling useServerProxy=true.";
+      if (!this.connectionConfig.useServerProxy) {
+        suggestion += " You can also configure server-side [docker].host_ip for direct endpoint access.";
+      }
+      return `Sandbox health check timed out after ${opts.readyTimeoutSeconds}s (${attempt} attempts). ${errorDetail} Connection context: ${context}. ${suggestion}`;
+    };
 
     // Wait until execd becomes reachable and passes health check.
     while (true) {
       if (Date.now() > deadline) {
         throw new SandboxReadyTimeoutException({
-          message: `Sandbox not ready: timed out waiting for health check (timeoutSeconds=${opts.readyTimeoutSeconds})`,
+          message: buildTimeoutMessage(),
         });
       }
+      attempt++;
       try {
         if (opts.healthCheck) {
           const ok = await opts.healthCheck(this);
-          if (ok) return;
+          if (ok) {
+            return;
+          }
         } else {
           const ok = await this.health.ping();
-          if (ok) return;
+          if (ok) {
+            return;
+          }
         }
-      } catch {
-        // ignore and retry
+        errorDetail = "Health check returned false continuously.";
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        errorDetail = `Last health check error: ${message}`;
       }
       await sleep(opts.pollingIntervalMillis);
     }
   }
-}
+}

package/src/services/egress.ts

@@ -0,0 +1,27 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { NetworkPolicy, NetworkRule } from "../models/sandboxes.js";
+
+export interface Egress {
+  getPolicy(): Promise<NetworkPolicy>;
+  /**
+   * Patch egress rules with sidecar merge semantics.
+   *
+   * Incoming rules take priority over existing rules with the same target.
+   * Existing rules for other targets remain unchanged. Within one patch payload,
+   * the first rule for a target wins. The current defaultAction is preserved.
+   */
+  patchRules(rules: NetworkRule[]): Promise<void>;
+}

package/src/services/execdCommands.ts

@@ -13,7 +13,13 @@
 // limitations under the License.
 
 import type { ExecutionHandlers } from "../models/execution.js";
-import type { CommandExecution, RunCommandOpts, ServerStreamEvent } from "../models/execd.js";
+import type {
+  CommandExecution,
+  CommandLogs,
+  CommandStatus,
+  RunCommandOpts,
+  ServerStreamEvent,
+} from "../models/execd.js";
 
 export interface ExecdCommands {
   /**
@@ -32,4 +38,37 @@ export 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>;
+
+  /**
+   * Create a bash session with optional working directory.
+   * Returns session ID for use with runInSession and deleteSession.
+   */
+  createSession(options?: { workingDirectory?: string }): Promise<string>;
+
+  /**
+   * Run a shell command in an existing bash session (SSE stream, same event shape as run).
+   * Optional workingDirectory and timeout apply to this run only; session state (e.g. env) persists.
+   */
+  runInSession(
+    sessionId: string,
+    command: string,
+    options?: { workingDirectory?: string; timeout?: number },
+    handlers?: ExecutionHandlers,
+    signal?: AbortSignal,
+  ): Promise<CommandExecution>;
+
+  /**
+   * Delete a bash session by ID. Frees resources; session ID must have been returned by createSession.
+   */
+  deleteSession(sessionId: string): Promise<void>;
+}

package/src/services/sandboxes.ts

@@ -38,5 +38,9 @@ export interface Sandboxes {
     req: RenewSandboxExpirationRequest,
   ): Promise<RenewSandboxExpirationResponse>;
 
-  getSandboxEndpoint(sandboxId: SandboxId, port: number): Promise<Endpoint>;
-}
+  getSandboxEndpoint(
+    sandboxId: SandboxId,
+    port: number,
+    useServerProxy?: boolean
+  ): Promise<Endpoint>;
+}