tensorlake 0.5.29 → 0.5.30

package/dist/index.d.cts

@@ -109,6 +109,7 @@ interface CreateSandboxResponse {
     sandboxId: string;
     status: SandboxStatus;
     routingHint?: string;
+    ingressEndpoint?: string;
     name?: string | null;
     terminationReason?: string;
     errorDetails?: unknown;
@@ -133,12 +134,14 @@ interface SandboxInfo {
     name?: string;
     allowUnauthenticatedAccess?: boolean;
     exposedPorts?: number[];
+    ingressEndpoint?: string;
     sandboxUrl?: string;
     routingHint?: string;
 }
 interface SandboxPortAccess {
     allowUnauthenticatedAccess: boolean;
     exposedPorts: number[];
+    ingressEndpoint?: string;
     sandboxUrl?: string;
 }
 /** Sandbox information plus the archival timestamp. */
@@ -337,6 +340,9 @@ interface SandboxOptions {
     organizationId?: string;
     projectId?: string;
     routingHint?: string;
+    resolveProxyInfo?: (identifier: string) => Promise<SandboxInfo & {
+        readonly traceId: string;
+    }>;
 }
 interface CreateAndConnectOptions extends CreateSandboxOptions {
     poolId?: string;
@@ -509,19 +515,22 @@ declare class Pty {
 declare class Sandbox {
     readonly sandboxId: string;
     traceId: string | null;
+    private readonly proxy;
     private readonly http;
-    private readonly baseUrl;
-    private readonly wsHeaders;
     private ownsSandbox;
     private lifecycleClient;
     private lifecycleIdentifier;
     private sandboxName;
     constructor(options: SandboxOptions);
+    private get baseUrl();
+    private get wsHeaders();
     get name(): string | null;
     /** @internal Used by client wiring to keep locally cached name in sync. */
     _setName(name: string | null): void;
     /** @internal Used by lifecycle operations to pin to canonical sandbox ID. */
     _setLifecycleIdentifier(identifier: string): void;
+    /** @internal Used by the lazy proxy resolver. */
+    _getLifecycleIdentifier(): string;
     /** @internal Used by SandboxClient.createAndConnect to set ownership. */
     _setOwner(client: SandboxClient): void;
     /**
@@ -534,9 +543,9 @@ declare class Sandbox {
     /**
      * Attach to an existing sandbox and return a connected handle.
      *
-     * Returns immediately without contacting the server. Call `sandbox.info()`
-     * to fetch the current state on demand. Does **not** auto-resume a suspended
-     * sandbox — call `sandbox.resume()` explicitly.
+     * When `proxyUrl` is omitted, resolves the sandbox first so the handle uses
+     * the correct cloud/region ingress endpoint. Does **not** auto-resume a
+     * suspended sandbox — call `sandbox.resume()` explicitly.
      */
     static connect(options: ConnectOptions & Partial<SandboxClientOptions>): Promise<Sandbox>;
     /** Get information about a snapshot by ID. No sandbox handle needed. */
@@ -1014,6 +1023,15 @@ declare class APIClient {
     requestOutput(applicationName: string, requestId: string): Promise<RequestOutput>;
 }
 
+/**
+ * Build a public sandbox URL from a server-provided ingress endpoint.
+ *
+ * `port` omitted or `9501` returns the management URL:
+ * `https://<sandbox-id>.<ingress-host>`. User ports use the public
+ * `<port>-<sandbox-id>.<ingress-host>` form.
+ */
+declare function sandboxUrlFromIngressEndpoint(ingressEndpoint: string, sandboxId: string, port?: number): string;
+
 /** Base exception for all sandbox-related errors. */
 declare class SandboxException extends Error {
     constructor(message: string);
@@ -1062,4 +1080,4 @@ declare class RequestExecutionError extends Error {
     constructor(message: string, functionName?: string);
 }
 
-export { APIClient, type ApiKeyIntrospection, type ApplicationBuildContext, type ApplicationBuildImageResult, type ApplicationBuildResponse, type ApplicationManifest, type ApplicationSummary, type ArchivedSandboxInfo, type BinaryPayload, type BuildInfo, type BuildLogEntry, type CheckpointOptions, type CheckpointType, CloudClient, type CloudClientOptions, type CommandResult, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CreateAndConnectOptions, type CreateApplicationBuildImageRequest, type CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type MouseButton, type NetworkConfig, type NewSecret, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, RemoteAPIError, type RequestErrorInfo, RequestExecutionError, RequestFailedError, type RequestInput, type RequestMetadata, RequestNotFinishedError, type RequestOutput, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, SandboxStatus, type Secret, type SecretsList, type SecretsPagination, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, type StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, type UpsertSecretResponse };
+export { APIClient, type ApiKeyIntrospection, type ApplicationBuildContext, type ApplicationBuildImageResult, type ApplicationBuildResponse, type ApplicationManifest, type ApplicationSummary, type ArchivedSandboxInfo, type BinaryPayload, type BuildInfo, type BuildLogEntry, type CheckpointOptions, type CheckpointType, CloudClient, type CloudClientOptions, type CommandResult, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CreateAndConnectOptions, type CreateApplicationBuildImageRequest, type CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type MouseButton, type NetworkConfig, type NewSecret, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, RemoteAPIError, type RequestErrorInfo, RequestExecutionError, RequestFailedError, type RequestInput, type RequestMetadata, RequestNotFinishedError, type RequestOutput, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, SandboxStatus, type Secret, type SecretsList, type SecretsPagination, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, type StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, type UpsertSecretResponse, sandboxUrlFromIngressEndpoint };

package/dist/index.d.ts

@@ -109,6 +109,7 @@ interface CreateSandboxResponse {
     sandboxId: string;
     status: SandboxStatus;
     routingHint?: string;
+    ingressEndpoint?: string;
     name?: string | null;
     terminationReason?: string;
     errorDetails?: unknown;
@@ -133,12 +134,14 @@ interface SandboxInfo {
     name?: string;
     allowUnauthenticatedAccess?: boolean;
     exposedPorts?: number[];
+    ingressEndpoint?: string;
     sandboxUrl?: string;
     routingHint?: string;
 }
 interface SandboxPortAccess {
     allowUnauthenticatedAccess: boolean;
     exposedPorts: number[];
+    ingressEndpoint?: string;
     sandboxUrl?: string;
 }
 /** Sandbox information plus the archival timestamp. */
@@ -337,6 +340,9 @@ interface SandboxOptions {
     organizationId?: string;
     projectId?: string;
     routingHint?: string;
+    resolveProxyInfo?: (identifier: string) => Promise<SandboxInfo & {
+        readonly traceId: string;
+    }>;
 }
 interface CreateAndConnectOptions extends CreateSandboxOptions {
     poolId?: string;
@@ -509,19 +515,22 @@ declare class Pty {
 declare class Sandbox {
     readonly sandboxId: string;
     traceId: string | null;
+    private readonly proxy;
     private readonly http;
-    private readonly baseUrl;
-    private readonly wsHeaders;
     private ownsSandbox;
     private lifecycleClient;
     private lifecycleIdentifier;
     private sandboxName;
     constructor(options: SandboxOptions);
+    private get baseUrl();
+    private get wsHeaders();
     get name(): string | null;
     /** @internal Used by client wiring to keep locally cached name in sync. */
     _setName(name: string | null): void;
     /** @internal Used by lifecycle operations to pin to canonical sandbox ID. */
     _setLifecycleIdentifier(identifier: string): void;
+    /** @internal Used by the lazy proxy resolver. */
+    _getLifecycleIdentifier(): string;
     /** @internal Used by SandboxClient.createAndConnect to set ownership. */
     _setOwner(client: SandboxClient): void;
     /**
@@ -534,9 +543,9 @@ declare class Sandbox {
     /**
      * Attach to an existing sandbox and return a connected handle.
      *
-     * Returns immediately without contacting the server. Call `sandbox.info()`
-     * to fetch the current state on demand. Does **not** auto-resume a suspended
-     * sandbox — call `sandbox.resume()` explicitly.
+     * When `proxyUrl` is omitted, resolves the sandbox first so the handle uses
+     * the correct cloud/region ingress endpoint. Does **not** auto-resume a
+     * suspended sandbox — call `sandbox.resume()` explicitly.
      */
     static connect(options: ConnectOptions & Partial<SandboxClientOptions>): Promise<Sandbox>;
     /** Get information about a snapshot by ID. No sandbox handle needed. */
@@ -1014,6 +1023,15 @@ declare class APIClient {
     requestOutput(applicationName: string, requestId: string): Promise<RequestOutput>;
 }
 
+/**
+ * Build a public sandbox URL from a server-provided ingress endpoint.
+ *
+ * `port` omitted or `9501` returns the management URL:
+ * `https://<sandbox-id>.<ingress-host>`. User ports use the public
+ * `<port>-<sandbox-id>.<ingress-host>` form.
+ */
+declare function sandboxUrlFromIngressEndpoint(ingressEndpoint: string, sandboxId: string, port?: number): string;
+
 /** Base exception for all sandbox-related errors. */
 declare class SandboxException extends Error {
     constructor(message: string);
@@ -1062,4 +1080,4 @@ declare class RequestExecutionError extends Error {
     constructor(message: string, functionName?: string);
 }
 
-export { APIClient, type ApiKeyIntrospection, type ApplicationBuildContext, type ApplicationBuildImageResult, type ApplicationBuildResponse, type ApplicationManifest, type ApplicationSummary, type ArchivedSandboxInfo, type BinaryPayload, type BuildInfo, type BuildLogEntry, type CheckpointOptions, type CheckpointType, CloudClient, type CloudClientOptions, type CommandResult, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CreateAndConnectOptions, type CreateApplicationBuildImageRequest, type CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type MouseButton, type NetworkConfig, type NewSecret, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, RemoteAPIError, type RequestErrorInfo, RequestExecutionError, RequestFailedError, type RequestInput, type RequestMetadata, RequestNotFinishedError, type RequestOutput, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, SandboxStatus, type Secret, type SecretsList, type SecretsPagination, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, type StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, type UpsertSecretResponse };
+export { APIClient, type ApiKeyIntrospection, type ApplicationBuildContext, type ApplicationBuildImageResult, type ApplicationBuildResponse, type ApplicationManifest, type ApplicationSummary, type ArchivedSandboxInfo, type BinaryPayload, type BuildInfo, type BuildLogEntry, type CheckpointOptions, type CheckpointType, CloudClient, type CloudClientOptions, type CommandResult, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CreateAndConnectOptions, type CreateApplicationBuildImageRequest, type CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type MouseButton, type NetworkConfig, type NewSecret, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, RemoteAPIError, type RequestErrorInfo, RequestExecutionError, RequestFailedError, type RequestInput, type RequestMetadata, RequestNotFinishedError, type RequestOutput, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, SandboxStatus, type Secret, type SecretsList, type SecretsPagination, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, type StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, type UpsertSecretResponse, sandboxUrlFromIngressEndpoint };

package/dist/index.js

@@ -19,7 +19,7 @@ var SDK_VERSION, API_URL, API_KEY, NAMESPACE, SANDBOX_PROXY_URL, DEFAULT_HTTP_TI
 var init_defaults = __esm({
   "src/defaults.ts"() {
     "use strict";
-    SDK_VERSION = "0.5.29";
+    SDK_VERSION = "0.5.30";
     API_URL = process.env.TENSORLAKE_API_URL ?? "https://api.tensorlake.ai";
     API_KEY = process.env.TENSORLAKE_API_KEY ?? void 0;
     NAMESPACE = process.env.INDEXIFY_NAMESPACE ?? "default";
@@ -2957,6 +2957,14 @@ function resolveProxyTarget(proxyUrl, sandboxId) {
     };
   }
 }
+function sandboxUrlFromIngressEndpoint(ingressEndpoint, sandboxId, port = 9501) {
+  const parsed = new URL(ingressEndpoint);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("ingressEndpoint must be an absolute http(s) URL");
+  }
+  const label = port === 9501 ? sandboxId : `${port}-${sandboxId}`;
+  return `${parsed.protocol}//${label}.${parsed.host}`;
+}
 function resolveSandboxLifecycleUrl(apiUrl) {
   if (isLocalhost(apiUrl)) return apiUrl;
   try {
@@ -3016,7 +3024,7 @@ function sendPtyFrame(socket, frame) {
     socket.send(frame, (error) => error ? reject(error) : resolve());
   });
 }
-var DEFAULT_PROCESS_USER, PTY_OP_DATA, PTY_OP_RESIZE, PTY_OP_READY, PTY_OP_EXIT, Pty, Sandbox;
+var DEFAULT_PROCESS_USER, SandboxProxyConnection, PTY_OP_DATA, PTY_OP_RESIZE, PTY_OP_READY, PTY_OP_EXIT, Pty, Sandbox;
 var init_sandbox = __esm({
   "src/sandbox.ts"() {
     "use strict";
@@ -3029,6 +3037,98 @@ var init_sandbox = __esm({
     init_sse();
     init_url();
     DEFAULT_PROCESS_USER = "tl-user";
+    SandboxProxyConnection = class {
+      constructor(sandbox, options) {
+        this.sandbox = sandbox;
+        this.options = options;
+        this.routingHint = options.routingHint;
+        this.http = this.configureProxy(
+          options.proxyUrl ?? SANDBOX_PROXY_URL,
+          options.sandboxId,
+          options.routingHint
+        );
+        this.resolveProxyInfo = options.resolveProxyInfo;
+      }
+      baseUrl = "";
+      wsHeaders = {};
+      http;
+      resolveProxyInfo;
+      resolvePromise = null;
+      routingHint;
+      async ensureResolved() {
+        if (this.resolveProxyInfo == null) {
+          return;
+        }
+        if (this.resolvePromise != null) {
+          return this.resolvePromise;
+        }
+        this.resolvePromise = this.resolveProxyInfo(this.sandbox._getLifecycleIdentifier()).then((info) => {
+          this.resolveProxyInfo = void 0;
+          this.sandbox.traceId = info.traceId;
+          this.sandbox._setLifecycleIdentifier(info.sandboxId);
+          this.sandbox._setName(info.name ?? null);
+          this.routingHint = this.routingHint ?? info.routingHint;
+          const proxyUrl = info.ingressEndpoint ?? this.options.proxyUrl ?? SANDBOX_PROXY_URL;
+          const nextHttp = this.configureProxy(proxyUrl, info.sandboxId, this.routingHint);
+          this.http.close();
+          this.http = nextHttp;
+        }).finally(() => {
+          this.resolvePromise = null;
+        });
+        return this.resolvePromise;
+      }
+      async requestJson(method, path2, options) {
+        await this.ensureResolved();
+        return this.http.requestJson(method, path2, options);
+      }
+      async requestBytes(method, path2, options) {
+        await this.ensureResolved();
+        return this.http.requestBytes(method, path2, options);
+      }
+      async requestStream(method, path2, options) {
+        await this.ensureResolved();
+        return this.http.requestStream(method, path2, options);
+      }
+      async requestResponse(method, path2, options) {
+        await this.ensureResolved();
+        return this.http.requestResponse(method, path2, options);
+      }
+      close() {
+        this.http.close();
+      }
+      configureProxy(proxyUrl, sandboxId, routingHint) {
+        const { baseUrl, hostHeader, sandboxIdHeader } = resolveProxyTarget(
+          proxyUrl,
+          sandboxId
+        );
+        this.baseUrl = baseUrl;
+        this.wsHeaders = {};
+        if (this.options.apiKey) {
+          this.wsHeaders.Authorization = `Bearer ${this.options.apiKey}`;
+        }
+        if (this.options.organizationId) {
+          this.wsHeaders["X-Forwarded-Organization-Id"] = this.options.organizationId;
+        }
+        if (this.options.projectId) {
+          this.wsHeaders["X-Forwarded-Project-Id"] = this.options.projectId;
+        }
+        if (hostHeader) {
+          this.wsHeaders.Host = hostHeader;
+        }
+        if (sandboxIdHeader) {
+          this.wsHeaders["X-Tensorlake-Sandbox-Id"] = sandboxIdHeader;
+        }
+        return new HttpClient({
+          baseUrl,
+          apiKey: this.options.apiKey,
+          organizationId: this.options.organizationId,
+          projectId: this.options.projectId,
+          hostHeader,
+          sandboxIdHeader,
+          routingHint
+        });
+      }
+    };
     PTY_OP_DATA = 0;
     PTY_OP_RESIZE = 1;
     PTY_OP_READY = 2;
@@ -3194,9 +3294,8 @@ var init_sandbox = __esm({
     Sandbox = class {
       sandboxId;
       traceId = null;
+      proxy;
       http;
-      baseUrl;
-      wsHeaders;
       ownsSandbox = false;
       lifecycleClient = null;
       lifecycleIdentifier;
@@ -3204,34 +3303,14 @@ var init_sandbox = __esm({
       constructor(options) {
         this.sandboxId = options.sandboxId;
         this.lifecycleIdentifier = options.sandboxId;
-        const proxyUrl = options.proxyUrl ?? SANDBOX_PROXY_URL;
-        const { baseUrl, hostHeader, sandboxIdHeader } = resolveProxyTarget(proxyUrl, options.sandboxId);
-        this.baseUrl = baseUrl;
-        this.wsHeaders = {};
-        if (options.apiKey) {
-          this.wsHeaders.Authorization = `Bearer ${options.apiKey}`;
-        }
-        if (options.organizationId) {
-          this.wsHeaders["X-Forwarded-Organization-Id"] = options.organizationId;
-        }
-        if (options.projectId) {
-          this.wsHeaders["X-Forwarded-Project-Id"] = options.projectId;
-        }
-        if (hostHeader) {
-          this.wsHeaders.Host = hostHeader;
-        }
-        if (sandboxIdHeader) {
-          this.wsHeaders["X-Tensorlake-Sandbox-Id"] = sandboxIdHeader;
-        }
-        this.http = new HttpClient({
-          baseUrl,
-          apiKey: options.apiKey,
-          organizationId: options.organizationId,
-          projectId: options.projectId,
-          hostHeader,
-          sandboxIdHeader,
-          routingHint: options.routingHint
-        });
+        this.proxy = new SandboxProxyConnection(this, options);
+        this.http = this.proxy;
+      }
+      get baseUrl() {
+        return this.proxy.baseUrl;
+      }
+      get wsHeaders() {
+        return this.proxy.wsHeaders;
       }
       get name() {
         return this.sandboxName;
@@ -3244,6 +3323,10 @@ var init_sandbox = __esm({
       _setLifecycleIdentifier(identifier) {
         this.lifecycleIdentifier = identifier;
       }
+      /** @internal Used by the lazy proxy resolver. */
+      _getLifecycleIdentifier() {
+        return this.lifecycleIdentifier;
+      }
       /** @internal Used by SandboxClient.createAndConnect to set ownership. */
       _setOwner(client) {
         this.ownsSandbox = true;
@@ -3270,9 +3353,9 @@ var init_sandbox = __esm({
       /**
        * Attach to an existing sandbox and return a connected handle.
        *
-       * Returns immediately without contacting the server. Call `sandbox.info()`
-       * to fetch the current state on demand. Does **not** auto-resume a suspended
-       * sandbox — call `sandbox.resume()` explicitly.
+       * When `proxyUrl` is omitted, resolves the sandbox first so the handle uses
+       * the correct cloud/region ingress endpoint. Does **not** auto-resume a
+       * suspended sandbox — call `sandbox.resume()` explicitly.
        */
       static async connect(options) {
         const { SandboxClient: SandboxClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
@@ -3686,6 +3769,7 @@ var init_sandbox = __esm({
       }
       /** Attach to an existing PTY session by ID and token and return a connected `Pty` handle. */
       async connectPty(sessionId, token, options) {
+        await this.proxy.ensureResolved();
         const wsUrl = new URL(this.ptyWsUrl(sessionId, token));
         const authToken = wsUrl.searchParams.get("token") ?? token;
         const pty = new Pty({
@@ -3711,6 +3795,7 @@ var init_sandbox = __esm({
       }
       /** Open a TCP tunnel to a port inside the sandbox and return the local listener. */
       async createTunnel(remotePort, options) {
+        await this.proxy.ensureResolved();
         return TcpTunnel.listen({
           baseUrl: this.baseUrl,
           wsHeaders: this.wsHeaders,
@@ -3722,6 +3807,7 @@ var init_sandbox = __esm({
       }
       /** Connect to a sandbox VNC session for programmatic desktop control. */
       async connectDesktop(options) {
+        await this.proxy.ensureResolved();
         const port = options?.port ?? 5901;
         const connectTimeout = options?.connectTimeout ?? 10;
         const startMs = Date.now();
@@ -4041,6 +4127,7 @@ var init_client = __esm({
         return {
           allowUnauthenticatedAccess: info.allowUnauthenticatedAccess ?? false,
           exposedPorts: dedupeAndSortPorts(info.exposedPorts ?? []),
+          ingressEndpoint: info.ingressEndpoint,
           sandboxUrl: info.sandboxUrl
         };
       }
@@ -4314,7 +4401,8 @@ var init_client = __esm({
           apiKey: this.apiKey,
           organizationId: this.organizationId,
           projectId: this.projectId,
-          routingHint
+          routingHint,
+          resolveProxyInfo: proxyUrl == null ? async (currentIdentifier) => this.get(currentIdentifier) : void 0
         });
       }
       /**
@@ -4330,8 +4418,12 @@ var init_client = __esm({
         const startupTimeout = options?.startupTimeout ?? 60;
         const result = options?.poolId != null ? await this.claim(options.poolId) : await this.create(options);
         const requestedName = options?.poolId != null ? null : options?.name ?? null;
-        const finishConnect = (routingHint, name) => {
-          const sandbox = this.connect(result.sandboxId, options?.proxyUrl, routingHint);
+        const finishConnect = (routingHint, name, ingressEndpoint) => {
+          const sandbox = this.connect(
+            result.sandboxId,
+            options?.proxyUrl ?? ingressEndpoint,
+            routingHint
+          );
           sandbox._setOwner(this);
           sandbox.traceId = result.traceId;
           sandbox._setLifecycleIdentifier(result.sandboxId);
@@ -4339,7 +4431,7 @@ var init_client = __esm({
           return sandbox;
         };
         if (result.status === "running" /* RUNNING */) {
-          return finishConnect(result.routingHint, result.name);
+          return finishConnect(result.routingHint, result.name, result.ingressEndpoint);
         }
         if (result.status === "suspended" /* SUSPENDED */ || result.status === "terminated" /* TERMINATED */) {
           throw new SandboxError(
@@ -4353,7 +4445,7 @@ var init_client = __esm({
         while (Date.now() < deadline) {
           const info = await this.get(result.sandboxId);
           if (info.status === "running" /* RUNNING */) {
-            return finishConnect(info.routingHint, info.name);
+            return finishConnect(info.routingHint, info.name, info.ingressEndpoint);
           }
           if (info.status === "suspended" /* SUSPENDED */ || info.status === "terminated" /* TERMINATED */) {
             throw new SandboxError(
@@ -5121,6 +5213,7 @@ var APIClient = class {
 // src/index.ts
 init_sandbox_image();
 init_image();
+init_url();
 init_errors();
 init_models();
 export {
@@ -5150,6 +5243,7 @@ export {
   StdinMode,
   TcpTunnel,
   createSandboxImage,
-  dockerfileContent
+  dockerfileContent,
+  sandboxUrlFromIngressEndpoint
 };
 //# sourceMappingURL=index.js.map