@daytona/sdk 0.197.0 → 0.198.0-alpha.1

package/esm/Sandbox.js

@@ -16,6 +16,13 @@ import { CODE_TOOLBOX_LANGUAGE_LABEL } from './Daytona.js';
 import { ComputerUse } from './ComputerUse.js';
 import { CodeInterpreter } from './CodeInterpreter.js';
 import { WithInstrumentation } from './utils/otel.decorator.js';
+function withEvents(target, _context) {
+    return function (...args) {
+        ;
+        this.ensureSubscribed();
+        return target.apply(this, args);
+    };
+}
 /**
  * Represents a Daytona Sandbox.
  *
@@ -48,6 +55,7 @@ import { WithInstrumentation } from './utils/otel.decorator.js';
  * @property {number} [autoPauseInterval] - Auto-pause interval in minutes
  * @property {number} [autoArchiveInterval] - Auto-archive interval in minutes
  * @property {number} [autoDeleteInterval] - Auto-delete interval in minutes
+ * @property {string} [autoDestroyAt] - When the Sandbox will be automatically destroyed (only set when a TTL is configured)
  * @property {Array<SandboxVolume>} [volumes] - Volumes attached to the Sandbox (not returned by
  * list results; call `refreshData()` on each item to populate)
  * @property {BuildInfo} [buildInfo] - Build information for the Sandbox if it was created from dynamic build
@@ -76,6 +84,7 @@ let Sandbox = (() => {
     let _createLspServer_decorators;
     let _setLabels_decorators;
     let _start_decorators;
+    let _recover_decorators;
     let _stop_decorators;
     let __experimental_fork_decorators;
     let __experimental_createSnapshot_decorators;
@@ -84,14 +93,18 @@ let Sandbox = (() => {
     let _waitUntilStarted_decorators;
     let _waitUntilStopped_decorators;
     let _refreshData_decorators;
+    let _refreshActivity_decorators;
     let _setAutostopInterval_decorators;
     let _setAutoPauseInterval_decorators;
+    let _setTtl_decorators;
     let _setAutoArchiveInterval_decorators;
     let _setAutoDeleteInterval_decorators;
     let _updateNetworkSettings_decorators;
     let _updateSecrets_decorators;
     let _updateEnv_decorators;
     let _getPreviewLink_decorators;
+    let _getSignedPreviewUrl_decorators;
+    let _expireSignedPreviewUrl_decorators;
     let _archive_decorators;
     let _resize_decorators;
     let _waitForResizeComplete_decorators;
@@ -101,36 +114,41 @@ let Sandbox = (() => {
     return class Sandbox {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
-            _getUserHomeDir_decorators = [WithInstrumentation()];
+            _getUserHomeDir_decorators = [WithInstrumentation(), withEvents];
             _getMetricsLatest_decorators = [WithInstrumentation()];
             _getMetrics_decorators = [WithInstrumentation()];
-            _getUserRootDir_decorators = [WithInstrumentation()];
-            _getWorkDir_decorators = [WithInstrumentation()];
-            _createLspServer_decorators = [WithInstrumentation()];
-            _setLabels_decorators = [WithInstrumentation()];
-            _start_decorators = [WithInstrumentation()];
-            _stop_decorators = [WithInstrumentation()];
-            __experimental_fork_decorators = [WithInstrumentation()];
-            __experimental_createSnapshot_decorators = [WithInstrumentation()];
-            _pause_decorators = [WithInstrumentation()];
-            _delete_decorators = [WithInstrumentation()];
-            _waitUntilStarted_decorators = [WithInstrumentation()];
-            _waitUntilStopped_decorators = [WithInstrumentation()];
-            _refreshData_decorators = [WithInstrumentation()];
-            _setAutostopInterval_decorators = [WithInstrumentation()];
+            _getUserRootDir_decorators = [WithInstrumentation(), withEvents];
+            _getWorkDir_decorators = [WithInstrumentation(), withEvents];
+            _createLspServer_decorators = [WithInstrumentation(), withEvents];
+            _setLabels_decorators = [WithInstrumentation(), withEvents];
+            _start_decorators = [WithInstrumentation(), withEvents];
+            _recover_decorators = [withEvents];
+            _stop_decorators = [WithInstrumentation(), withEvents];
+            __experimental_fork_decorators = [WithInstrumentation(), withEvents];
+            __experimental_createSnapshot_decorators = [WithInstrumentation(), withEvents];
+            _pause_decorators = [WithInstrumentation(), withEvents];
+            _delete_decorators = [WithInstrumentation(), withEvents];
+            _waitUntilStarted_decorators = [WithInstrumentation(), withEvents];
+            _waitUntilStopped_decorators = [WithInstrumentation(), withEvents];
+            _refreshData_decorators = [WithInstrumentation(), withEvents];
+            _refreshActivity_decorators = [withEvents];
+            _setAutostopInterval_decorators = [WithInstrumentation(), withEvents];
             _setAutoPauseInterval_decorators = [WithInstrumentation()];
-            _setAutoArchiveInterval_decorators = [WithInstrumentation()];
-            _setAutoDeleteInterval_decorators = [WithInstrumentation()];
+            _setTtl_decorators = [WithInstrumentation()];
+            _setAutoArchiveInterval_decorators = [WithInstrumentation(), withEvents];
+            _setAutoDeleteInterval_decorators = [WithInstrumentation(), withEvents];
             _updateNetworkSettings_decorators = [WithInstrumentation()];
             _updateSecrets_decorators = [WithInstrumentation()];
             _updateEnv_decorators = [WithInstrumentation()];
-            _getPreviewLink_decorators = [WithInstrumentation()];
-            _archive_decorators = [WithInstrumentation()];
-            _resize_decorators = [WithInstrumentation()];
-            _waitForResizeComplete_decorators = [WithInstrumentation()];
-            _createSshAccess_decorators = [WithInstrumentation()];
-            _revokeSshAccess_decorators = [WithInstrumentation()];
-            _validateSshAccess_decorators = [WithInstrumentation()];
+            _getPreviewLink_decorators = [WithInstrumentation(), withEvents];
+            _getSignedPreviewUrl_decorators = [withEvents];
+            _expireSignedPreviewUrl_decorators = [withEvents];
+            _archive_decorators = [WithInstrumentation(), withEvents];
+            _resize_decorators = [WithInstrumentation(), withEvents];
+            _waitForResizeComplete_decorators = [WithInstrumentation(), withEvents];
+            _createSshAccess_decorators = [WithInstrumentation(), withEvents];
+            _revokeSshAccess_decorators = [WithInstrumentation(), withEvents];
+            _validateSshAccess_decorators = [WithInstrumentation(), withEvents];
             __esDecorate(this, null, _getUserHomeDir_decorators, { kind: "method", name: "getUserHomeDir", static: false, private: false, access: { has: obj => "getUserHomeDir" in obj, get: obj => obj.getUserHomeDir }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getMetricsLatest_decorators, { kind: "method", name: "getMetricsLatest", static: false, private: false, access: { has: obj => "getMetricsLatest" in obj, get: obj => obj.getMetricsLatest }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getMetrics_decorators, { kind: "method", name: "getMetrics", static: false, private: false, access: { has: obj => "getMetrics" in obj, get: obj => obj.getMetrics }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -139,6 +157,7 @@ let Sandbox = (() => {
             __esDecorate(this, null, _createLspServer_decorators, { kind: "method", name: "createLspServer", static: false, private: false, access: { has: obj => "createLspServer" in obj, get: obj => obj.createLspServer }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _setLabels_decorators, { kind: "method", name: "setLabels", static: false, private: false, access: { has: obj => "setLabels" in obj, get: obj => obj.setLabels }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _start_decorators, { kind: "method", name: "start", static: false, private: false, access: { has: obj => "start" in obj, get: obj => obj.start }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _recover_decorators, { kind: "method", name: "recover", static: false, private: false, access: { has: obj => "recover" in obj, get: obj => obj.recover }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _stop_decorators, { kind: "method", name: "stop", static: false, private: false, access: { has: obj => "stop" in obj, get: obj => obj.stop }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, __experimental_fork_decorators, { kind: "method", name: "_experimental_fork", static: false, private: false, access: { has: obj => "_experimental_fork" in obj, get: obj => obj._experimental_fork }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, __experimental_createSnapshot_decorators, { kind: "method", name: "_experimental_createSnapshot", static: false, private: false, access: { has: obj => "_experimental_createSnapshot" in obj, get: obj => obj._experimental_createSnapshot }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -147,14 +166,18 @@ let Sandbox = (() => {
             __esDecorate(this, null, _waitUntilStarted_decorators, { kind: "method", name: "waitUntilStarted", static: false, private: false, access: { has: obj => "waitUntilStarted" in obj, get: obj => obj.waitUntilStarted }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _waitUntilStopped_decorators, { kind: "method", name: "waitUntilStopped", static: false, private: false, access: { has: obj => "waitUntilStopped" in obj, get: obj => obj.waitUntilStopped }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _refreshData_decorators, { kind: "method", name: "refreshData", static: false, private: false, access: { has: obj => "refreshData" in obj, get: obj => obj.refreshData }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _refreshActivity_decorators, { kind: "method", name: "refreshActivity", static: false, private: false, access: { has: obj => "refreshActivity" in obj, get: obj => obj.refreshActivity }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _setAutostopInterval_decorators, { kind: "method", name: "setAutostopInterval", static: false, private: false, access: { has: obj => "setAutostopInterval" in obj, get: obj => obj.setAutostopInterval }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _setAutoPauseInterval_decorators, { kind: "method", name: "setAutoPauseInterval", static: false, private: false, access: { has: obj => "setAutoPauseInterval" in obj, get: obj => obj.setAutoPauseInterval }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _setTtl_decorators, { kind: "method", name: "setTtl", static: false, private: false, access: { has: obj => "setTtl" in obj, get: obj => obj.setTtl }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _setAutoArchiveInterval_decorators, { kind: "method", name: "setAutoArchiveInterval", static: false, private: false, access: { has: obj => "setAutoArchiveInterval" in obj, get: obj => obj.setAutoArchiveInterval }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _setAutoDeleteInterval_decorators, { kind: "method", name: "setAutoDeleteInterval", static: false, private: false, access: { has: obj => "setAutoDeleteInterval" in obj, get: obj => obj.setAutoDeleteInterval }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _updateNetworkSettings_decorators, { kind: "method", name: "updateNetworkSettings", static: false, private: false, access: { has: obj => "updateNetworkSettings" in obj, get: obj => obj.updateNetworkSettings }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _updateSecrets_decorators, { kind: "method", name: "updateSecrets", static: false, private: false, access: { has: obj => "updateSecrets" in obj, get: obj => obj.updateSecrets }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _updateEnv_decorators, { kind: "method", name: "updateEnv", static: false, private: false, access: { has: obj => "updateEnv" in obj, get: obj => obj.updateEnv }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getPreviewLink_decorators, { kind: "method", name: "getPreviewLink", static: false, private: false, access: { has: obj => "getPreviewLink" in obj, get: obj => obj.getPreviewLink }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getSignedPreviewUrl_decorators, { kind: "method", name: "getSignedPreviewUrl", static: false, private: false, access: { has: obj => "getSignedPreviewUrl" in obj, get: obj => obj.getSignedPreviewUrl }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _expireSignedPreviewUrl_decorators, { kind: "method", name: "expireSignedPreviewUrl", static: false, private: false, access: { has: obj => "expireSignedPreviewUrl" in obj, get: obj => obj.expireSignedPreviewUrl }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _archive_decorators, { kind: "method", name: "archive", static: false, private: false, access: { has: obj => "archive" in obj, get: obj => obj.archive }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _resize_decorators, { kind: "method", name: "resize", static: false, private: false, access: { has: obj => "resize" in obj, get: obj => obj.resize }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _waitForResizeComplete_decorators, { kind: "method", name: "waitForResizeComplete", static: false, private: false, access: { has: obj => "waitForResizeComplete" in obj, get: obj => obj.waitForResizeComplete }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -167,6 +190,7 @@ let Sandbox = (() => {
         axiosInstance;
         sandboxApi;
         getAnalyticsApiUrl;
+        subscriptionManager;
         fs;
         git;
         process;
@@ -194,6 +218,7 @@ let Sandbox = (() => {
         autoPauseInterval;
         autoArchiveInterval;
         autoDeleteInterval;
+        autoDestroyAt;
         volumes;
         buildInfo;
         createdAt;
@@ -207,25 +232,27 @@ let Sandbox = (() => {
         infoApi;
         serverApi;
         systemApi;
+        stateWaiters = [];
+        stateWaiterErrorMessageFns = new WeakMap();
+        subId;
         /**
-         * Creates a new Sandbox instance
+         * Creates a new Sandbox instance.
+         *
+         * Internal: obtain sandboxes via {@link Daytona.create}, {@link Daytona.get}, or
+         * {@link Daytona.list} rather than constructing directly.
          *
          * @param {SandboxDto} sandboxDto - The API Sandbox instance
+         * @param {SandboxApi} sandboxApi - API client for Sandbox operations
+         * @param {InfoApi} infoApi - API client for info operations
+         * @param {EventSubscriptionManager} subscriptionManager - Event subscription manager for real-time updates
          */
-        constructor(sandboxDto, clientConfig, axiosInstance, sandboxApi, getAnalyticsApiUrl) {
+        constructor(sandboxDto, clientConfig, axiosInstance, sandboxApi, getAnalyticsApiUrl, subscriptionManager) {
             this.clientConfig = clientConfig;
             this.axiosInstance = axiosInstance;
             this.sandboxApi = sandboxApi;
             this.getAnalyticsApiUrl = getAnalyticsApiUrl;
+            this.subscriptionManager = subscriptionManager;
             this.processSandboxDto(sandboxDto);
-            // Set the toolbox base URL
-            let baseUrl = this.toolboxProxyUrl;
-            if (!baseUrl.endsWith('/')) {
-                baseUrl += '/';
-            }
-            this.axiosInstance.defaults.baseURL = baseUrl + this.id;
-            this.clientConfig.basePath = this.axiosInstance.defaults.baseURL;
-            // Initialize Services
             const getPreviewToken = async () => (await this.getPreviewLink(1)).token;
             this.fs = new FileSystem(this.clientConfig, new FileSystemApi(this.clientConfig, '', this.axiosInstance));
             this.git = new Git(new GitApi(this.clientConfig, '', this.axiosInstance));
@@ -236,6 +263,7 @@ let Sandbox = (() => {
             this.infoApi = new InfoApi(this.clientConfig, '', this.axiosInstance);
             this.serverApi = new ServerApi(this.clientConfig, '', this.axiosInstance);
             this.systemApi = new SystemApi(this.clientConfig, '', this.axiosInstance);
+            this.subscribeToEvents();
         }
         /**
          * Gets the user's home directory path for the logged in user inside the Sandbox.
@@ -454,9 +482,16 @@ let Sandbox = (() => {
                 timeout: timeout * 1000,
             });
             const sandboxDto = response.data;
-            const forkedSandbox = new Sandbox(sandboxDto, structuredClone(this.clientConfig), Daytona.createAxiosInstance(), this.sandboxApi, this.getAnalyticsApiUrl);
+            const sandboxWithProxyUrl = sandboxDto.toolboxProxyUrl
+                ? sandboxDto
+                : {
+                    ...sandboxDto,
+                    toolboxProxyUrl: (await this.sandboxApi.getToolboxProxyUrl(sandboxDto.id)).data.url,
+                };
+            const forkedSandbox = new Sandbox(sandboxWithProxyUrl, structuredClone(this.clientConfig), Daytona.createAxiosInstance(), this.sandboxApi, this.getAnalyticsApiUrl, this.subscriptionManager);
             const timeElapsed = Date.now() - startTime;
-            await forkedSandbox.waitUntilStarted(timeout ? Math.max(0.001, timeout - timeElapsed / 1000) : timeout);
+            const remainingTimeout = timeout ? Math.max(0.001, timeout - timeElapsed / 1000) : timeout;
+            await forkedSandbox.waitUntilStarted(remainingTimeout);
             return forkedSandbox;
         }
         /**
@@ -484,34 +519,19 @@ let Sandbox = (() => {
             }
             const startTime = Date.now();
             const req = { name };
-            await this.sandboxApi.createSandboxSnapshot(this.id, req, undefined, {
+            const response = await this.sandboxApi.createSandboxSnapshot(this.id, req, undefined, {
                 timeout: timeout * 1000,
             });
-            await this.refreshData();
+            this.processSandboxDto(response.data);
             const timeElapsed = Date.now() - startTime;
             const remainingTimeout = timeout ? Math.max(0.001, timeout - timeElapsed / 1000) : timeout;
             await this.waitForSnapshotComplete(remainingTimeout);
         }
         async waitForSnapshotComplete(timeout) {
-            let checkInterval = 100;
-            const startTime = Date.now();
-            while (this.state === SandboxState.SNAPSHOTTING) {
-                await this.refreshData();
-                // @ts-expect-error this.refreshData() can modify this.state so this check is fine
-                if (this.state === SandboxState.ERROR || this.state === SandboxState.BUILD_FAILED) {
-                    throw new DaytonaError(`Sandbox ${this.id} snapshot failed with state: ${this.state}, error reason: ${this.errorReason}`);
-                }
-                if (this.state !== SandboxState.SNAPSHOTTING) {
-                    return;
-                }
-                if (timeout !== 0 && Date.now() - startTime > timeout * 1000) {
-                    throw new DaytonaTimeoutError('Sandbox snapshot did not complete within the timeout period');
-                }
-                await new Promise((resolve) => setTimeout(resolve, checkInterval));
-                if (Date.now() - startTime > 5000) {
-                    checkInterval = Math.min(checkInterval * 1.1, 1000);
-                }
-            }
+            const errorStates = [SandboxState.ERROR, SandboxState.BUILD_FAILED];
+            const excludeStates = new Set([SandboxState.SNAPSHOTTING, ...errorStates]);
+            const targetStates = Object.values(SandboxState).filter((s) => !excludeStates.has(s));
+            return this.waitForState(targetStates, errorStates, timeout, 'Sandbox snapshot did not complete within the timeout period', (state) => `Sandbox ${this.id} snapshot failed with state: ${state}, error reason: ${this.errorReason}`);
         }
         /**
          * Pauses the Sandbox, freezing all running processes.
@@ -542,31 +562,47 @@ let Sandbox = (() => {
             await this.refreshData();
             const timeElapsed = Date.now() - startTime;
             const remainingTimeout = timeout ? Math.max(0.001, timeout - timeElapsed / 1000) : timeout;
-            await this.waitForPauseComplete(remainingTimeout);
-        }
-        async waitForPauseComplete(timeout) {
-            let checkInterval = 100;
-            const startTime = Date.now();
-            while (this.state === SandboxState.PAUSING) {
-                await this.refreshData();
-                // @ts-expect-error this.refreshData() can modify this.state so this check is fine
-                if (this.state === SandboxState.ERROR) {
-                    throw new DaytonaError(`Sandbox ${this.id} pause failed with state: ${this.state}, error reason: ${this.errorReason}`);
-                }
-                if (timeout > 0 && (Date.now() - startTime) / 1000 >= timeout) {
-                    throw new DaytonaError(`Sandbox ${this.id} failed to pause within ${timeout} seconds`);
-                }
-                await new Promise((resolve) => globalThis.setTimeout(resolve, checkInterval));
-                checkInterval = Math.min(checkInterval * 1.5, 1000);
-            }
+            // Main's contract: pause completes when the sandbox has *left* PAUSING
+            // (paused, stopped, archived, ...), not only on exactly PAUSED.
+            const errorStates = [SandboxState.ERROR, SandboxState.BUILD_FAILED];
+            const excludeStates = new Set([SandboxState.PAUSING, ...errorStates]);
+            const targetStates = Object.values(SandboxState).filter((s) => !excludeStates.has(s));
+            await this.waitForState(targetStates, errorStates, remainingTimeout, 'Sandbox failed to become paused within the timeout period', (state) => `Sandbox ${this.id} pause failed with state: ${state}, error reason: ${this.errorReason}`);
         }
         /**
          * Deletes the Sandbox.
+         *
+         * By default this returns as soon as the deletion request is accepted (matching
+         * historical behavior). Pass `wait = true` to block until the Sandbox reaches
+         * the 'destroyed' state.
+         *
+         * @param {number} [timeout] - Timeout in seconds for the request — and, when
+         *                            `wait` is true, for reaching 'destroyed'. 0 means no timeout.
+         *                            Defaults to 60-second timeout.
+         * @param {boolean} [wait] - If true, wait until the Sandbox is destroyed. Defaults to false.
          * @returns {Promise<void>}
          */
-        async delete(timeout = 60) {
-            await this.sandboxApi.deleteSandbox(this.id, undefined, { timeout: timeout * 1000 });
-            this.refreshDataSafe();
+        async delete(timeout = 60, wait = false) {
+            if (timeout < 0) {
+                throw new DaytonaValidationError('Timeout must be a non-negative number');
+            }
+            const startTime = Date.now();
+            const response = await this.sandboxApi.deleteSandbox(this.id, undefined, { timeout: timeout * 1000 });
+            if (response.data) {
+                this.processSandboxDto(response.data);
+            }
+            try {
+                if (wait && this.state !== SandboxState.DESTROYED) {
+                    const timeElapsed = Date.now() - startTime;
+                    await this.waitForState([SandboxState.DESTROYED], [SandboxState.ERROR, SandboxState.BUILD_FAILED], timeout ? Math.max(0.001, timeout - timeElapsed / 1000) : timeout, 'Sandbox failed to be destroyed within the timeout period', (state) => `Sandbox ${this.id} failed to delete with state: ${state}, error reason: ${this.errorReason}`, true);
+                }
+            }
+            finally {
+                if (this.subId) {
+                    this.subscriptionManager.unsubscribe(this.subId);
+                    this.subId = undefined;
+                }
+            }
         }
         /**
          * Waits for the Sandbox to reach the 'started' state.
@@ -583,26 +619,10 @@ let Sandbox = (() => {
             if (timeout < 0) {
                 throw new DaytonaValidationError('Timeout must be a non-negative number');
             }
-            let checkInterval = 100;
-            const startTime = Date.now();
-            while (this.state !== 'started') {
-                await this.refreshData();
-                // @ts-expect-error this.refreshData() can modify this.state so this check is fine
-                if (this.state === 'started') {
-                    return;
-                }
-                if (this.state === 'error') {
-                    const errMsg = `Sandbox ${this.id} failed to start with status: ${this.state}, error reason: ${this.errorReason}`;
-                    throw new DaytonaError(errMsg);
-                }
-                if (timeout !== 0 && Date.now() - startTime > timeout * 1000) {
-                    throw new DaytonaTimeoutError('Sandbox failed to become ready within the timeout period');
-                }
-                await new Promise((resolve) => setTimeout(resolve, checkInterval));
-                if (Date.now() - startTime > 5000) {
-                    checkInterval = Math.min(checkInterval * 1.1, 1000);
-                }
+            if (this.state === SandboxState.STARTED) {
+                return;
             }
+            return this.waitForState([SandboxState.STARTED], [SandboxState.ERROR, SandboxState.BUILD_FAILED], timeout, 'Sandbox failed to become ready within the timeout period', (state) => `Sandbox ${this.id} failed to start with status: ${state}, error reason: ${this.errorReason}`);
         }
         /**
          * Wait for Sandbox to reach 'stopped' state.
@@ -619,27 +639,11 @@ let Sandbox = (() => {
             if (timeout < 0) {
                 throw new DaytonaValidationError('Timeout must be a non-negative number');
             }
-            let checkInterval = 100;
-            const startTime = Date.now();
             // Treat destroyed as stopped to cover ephemeral sandboxes that are automatically deleted after stopping
-            while (this.state !== 'stopped' && this.state !== 'destroyed') {
-                this.refreshDataSafe();
-                // @ts-expect-error this.refreshData() can modify this.state so this check is fine
-                if (this.state === 'stopped' || this.state === 'destroyed') {
-                    return;
-                }
-                if (this.state === 'error') {
-                    const errMsg = `Sandbox failed to stop with status: ${this.state}, error reason: ${this.errorReason}`;
-                    throw new DaytonaError(errMsg);
-                }
-                if (timeout !== 0 && Date.now() - startTime > timeout * 1000) {
-                    throw new DaytonaTimeoutError('Sandbox failed to become stopped within the timeout period');
-                }
-                await new Promise((resolve) => setTimeout(resolve, checkInterval));
-                if (Date.now() - startTime > 5000) {
-                    checkInterval = Math.min(checkInterval * 1.1, 1000);
-                }
+            if (this.state === SandboxState.STOPPED || this.state === SandboxState.DESTROYED) {
+                return;
             }
+            return this.waitForState([SandboxState.STOPPED, SandboxState.DESTROYED], [SandboxState.ERROR, SandboxState.BUILD_FAILED], timeout, 'Sandbox failed to become stopped within the timeout period', (state) => `Sandbox failed to stop with status: ${state}, error reason: ${this.errorReason}`, true);
         }
         /**
          * Refreshes the Sandbox data from the API.
@@ -726,6 +730,30 @@ let Sandbox = (() => {
             await this.sandboxApi.setAutoPauseInterval(this.id, interval);
             this.autoPauseInterval = interval;
         }
+        /**
+         * Set the TTL (maximum time to live) for the Sandbox.
+         *
+         * The Sandbox will be destroyed once the TTL elapses, counted as wall-clock time regardless of the
+         * Sandbox state - even if it is stopped, paused, or archived. Calling this method re-anchors the
+         * deadline from the current time. Call `refreshData()` afterwards to read the updated `autoDestroyAt`.
+         *
+         * @param {number} ttlMinutes - Number of minutes from now after which the Sandbox will be destroyed.
+         *                           Set to 0 to disable the TTL.
+         * @returns {Promise<void>}
+         * @throws {DaytonaError} - `DaytonaError` - If ttlMinutes is not a non-negative integer
+         *
+         * @example
+         * // Destroy the Sandbox 1 hour from now
+         * await sandbox.setTtl(60);
+         * // Or disable the TTL
+         * await sandbox.setTtl(0);
+         */
+        async setTtl(ttlMinutes) {
+            if (!Number.isInteger(ttlMinutes) || ttlMinutes < 0) {
+                throw new DaytonaValidationError('ttlMinutes must be a non-negative integer');
+            }
+            await this.sandboxApi.setTtl(this.id, ttlMinutes);
+        }
         /**
          * Set the auto-archive interval for the Sandbox.
          *
@@ -948,25 +976,13 @@ let Sandbox = (() => {
             if (timeout < 0) {
                 throw new DaytonaValidationError('Timeout must be a non-negative number');
             }
-            let checkInterval = 100;
-            const startTime = Date.now();
-            while (this.state === SandboxState.RESIZING) {
-                await this.refreshData();
-                // @ts-expect-error this.refreshData() can modify this.state so this check is fine
-                if (this.state === SandboxState.ERROR || this.state === SandboxState.BUILD_FAILED) {
-                    throw new DaytonaError(`Sandbox ${this.id} resize failed with state: ${this.state}, error reason: ${this.errorReason}`);
-                }
-                if (this.state !== SandboxState.RESIZING) {
-                    return;
-                }
-                if (timeout !== 0 && Date.now() - startTime > timeout * 1000) {
-                    throw new DaytonaTimeoutError('Sandbox resize did not complete within the timeout period');
-                }
-                await new Promise((resolve) => setTimeout(resolve, checkInterval));
-                if (Date.now() - startTime > 5000) {
-                    checkInterval = Math.min(checkInterval * 1.1, 1000);
-                }
+            if (this.state !== SandboxState.RESIZING) {
+                return;
             }
+            const errorStates = [SandboxState.ERROR, SandboxState.BUILD_FAILED];
+            const excludeStates = new Set([SandboxState.RESIZING, ...errorStates]);
+            const targetStates = Object.values(SandboxState).filter((s) => !excludeStates.has(s));
+            return this.waitForState(targetStates, errorStates, timeout, 'Sandbox resize did not complete within the timeout period', (state) => `Sandbox ${this.id} resize failed with state: ${state}, error reason: ${this.errorReason}`);
         }
         /**
          * Creates an SSH access token for the sandbox.
@@ -995,6 +1011,172 @@ let Sandbox = (() => {
         async validateSshAccess(token) {
             return (await this.sandboxApi.validateSshAccess(token)).data;
         }
+        /**
+         * Subscribes to real-time events for this sandbox.
+         * Auto-updates sandbox metadata on every event.
+         */
+        subscribeToEvents() {
+            if (this.subId) {
+                return;
+            }
+            this.subId = this.subscriptionManager.subscribe(this.id, this.handleEvent.bind(this), [
+                'sandbox.state.updated',
+                'sandbox.created',
+            ]);
+        }
+        ensureSubscribed() {
+            if (this.subId) {
+                if (this.subscriptionManager.refresh(this.subId)) {
+                    return;
+                }
+                this.subId = undefined;
+            }
+            this.subscribeToEvents();
+        }
+        handleEvent(eventName, data) {
+            if (!data || typeof data !== 'object')
+                return;
+            const raw = data.sandbox ?? data;
+            if (!raw || typeof raw !== 'object')
+                return;
+            if (eventName === 'sandbox.created') {
+                this.processSandboxDto(raw);
+                return;
+            }
+            const newState = raw.state ?? data.newState;
+            if (newState) {
+                this.applyState(newState);
+            }
+        }
+        /**
+         * Waits for the sandbox to reach one of the target states.
+         * Throws on error states or timeout.
+         *
+         * @param targetStates - States that indicate success.
+         * @param errorStates - States that indicate failure.
+         * @param timeout - Maximum time to wait in seconds. 0 means no timeout.
+         * @param timeoutMessage - Error message when timeout is reached.
+         * @param errorMessageFn - Function that produces an error message from the current state.
+         * @param safeRefresh - If true, use refreshDataSafe() for polling (for delete operations where 404 is expected).
+         */
+        waitForState(targetStates, errorStates, timeout, timeoutMessage, errorMessageFn, safeRefresh = false) {
+            this.ensureSubscribed();
+            return new Promise((resolve, reject) => {
+                let timeoutTimer = null;
+                let pollTimer = null;
+                let settled = false;
+                const waiter = {
+                    targetStates: new Set(targetStates),
+                    errorStates: new Set(errorStates),
+                    resolve: (_) => {
+                        if (settled)
+                            return;
+                        cleanup();
+                        resolve();
+                    },
+                    reject: (err) => {
+                        if (settled)
+                            return;
+                        cleanup();
+                        reject(err);
+                    },
+                };
+                this.stateWaiters.push(waiter);
+                this.stateWaiterErrorMessageFns.set(waiter, errorMessageFn);
+                const cleanup = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (timeoutTimer)
+                        clearTimeout(timeoutTimer);
+                    if (pollTimer)
+                        clearTimeout(pollTimer);
+                    this.removeStateWaiter(waiter);
+                };
+                // Fast-path only on cached *target* states (parity with main's pre-check).
+                // Cached error states are deliberately NOT evaluated here — main always
+                // refreshed before failing, so a stale ERROR must survive one refresh.
+                if (this.state && waiter.targetStates.has(this.state)) {
+                    waiter.resolve(this.state);
+                    return;
+                }
+                if (timeout !== 0) {
+                    timeoutTimer = setTimeout(() => {
+                        void (async () => {
+                            if (settled)
+                                return;
+                            // Parity with main: complete one final refresh-then-evaluate before
+                            // rejecting, so a clamped/short timeout still observes the latest state.
+                            let refreshed = false;
+                            try {
+                                if (safeRefresh) {
+                                    refreshed = await this.refreshDataSafe();
+                                }
+                                else {
+                                    await this.refreshData();
+                                    refreshed = true;
+                                }
+                            }
+                            catch {
+                                // fall through to the timeout rejection below
+                            }
+                            if (!settled) {
+                                // Explicit evaluation: applyState() no-ops on unchanged state, so a
+                                // persistent error state would otherwise time out generically here.
+                                // Only evaluate when the refresh succeeded — a failed refresh leaves
+                                // the cached state stale and must not be treated as authoritative.
+                                if (refreshed && this.checkStateWaiter(waiter, this.state)) {
+                                    return;
+                                }
+                                cleanup();
+                                reject(new DaytonaTimeoutError(timeoutMessage));
+                            }
+                        })();
+                    }, timeout * 1000);
+                }
+                // Poll as a safety net for missed state changes. With an active event subscription
+                // a sparse 1s cadence suffices; without events (polling mode) replicate main's
+                // cadence exactly: 100ms steady for the first 5s, then exponential backoff capped at 1s.
+                const streaming = !!this.subId;
+                const pollStart = Date.now();
+                let pollInterval = streaming ? 1000 : 100;
+                const doPoll = async () => {
+                    if (settled)
+                        return;
+                    let refreshed = false;
+                    try {
+                        if (safeRefresh) {
+                            refreshed = await this.refreshDataSafe();
+                        }
+                        else {
+                            await this.refreshData();
+                            refreshed = true;
+                        }
+                    }
+                    catch (error) {
+                        waiter.reject(error instanceof Error ? error : new DaytonaError(String(error)));
+                        return;
+                    }
+                    if (!settled) {
+                        // Evaluate the refreshed state explicitly: applyState() no-ops when the
+                        // state is unchanged, so a persistent error state would otherwise never
+                        // reject the waiter. Only evaluate when the refresh succeeded — a failed
+                        // safe refresh leaves the cached state stale, so keep polling instead.
+                        if (refreshed && this.checkStateWaiter(waiter, this.state)) {
+                            return;
+                        }
+                        if (!streaming && Date.now() - pollStart > 5000) {
+                            pollInterval = Math.min(pollInterval * 1.1, 1000);
+                        }
+                        pollTimer = setTimeout(() => {
+                            void doPoll();
+                        }, pollInterval);
+                    }
+                };
+                // First poll runs immediately (main refreshed before any state evaluation).
+                void doPoll();
+            });
+        }
         /**
          * Assigns the API sandbox data to the Sandbox object.
          *
@@ -1002,6 +1184,7 @@ let Sandbox = (() => {
          * @returns {void}
          */
         processSandboxDto(sandboxDto) {
+            const newState = sandboxDto.state;
             this.id = sandboxDto.id;
             this.name = sandboxDto.name;
             this.organizationId = sandboxDto.organizationId;
@@ -1014,7 +1197,6 @@ let Sandbox = (() => {
             this.gpu = sandboxDto.gpu;
             this.memory = sandboxDto.memory;
             this.disk = sandboxDto.disk;
-            this.state = sandboxDto.state;
             this.errorReason = sandboxDto.errorReason;
             this.recoverable = sandboxDto.recoverable;
             this.backupState = sandboxDto.backupState;
@@ -1022,10 +1204,10 @@ let Sandbox = (() => {
             this.autoPauseInterval = sandboxDto.autoPauseInterval;
             this.autoArchiveInterval = sandboxDto.autoArchiveInterval;
             this.autoDeleteInterval = sandboxDto.autoDeleteInterval;
+            this.autoDestroyAt = sandboxDto.autoDestroyAt;
             this.createdAt = sandboxDto.createdAt;
             this.updatedAt = sandboxDto.updatedAt;
             this.lastActivityAt = sandboxDto.lastActivityAt;
-            this.toolboxProxyUrl = sandboxDto.toolboxProxyUrl;
             // Fields only present in the full SandboxDto (not returned by list endpoint)
             if ('env' in sandboxDto) {
                 this.env = sandboxDto.env;
@@ -1037,6 +1219,21 @@ let Sandbox = (() => {
                 this.buildInfo = sandboxDto.buildInfo;
                 this.backupCreatedAt = sandboxDto.backupCreatedAt;
             }
+            const newProxyUrl = sandboxDto.toolboxProxyUrl;
+            if (newProxyUrl && newProxyUrl !== this.toolboxProxyUrl && this.axiosInstance) {
+                let baseUrl = newProxyUrl;
+                if (!baseUrl.endsWith('/')) {
+                    baseUrl += '/';
+                }
+                this.axiosInstance.defaults.baseURL = baseUrl + this.id;
+                this.clientConfig.basePath = this.axiosInstance.defaults.baseURL;
+            }
+            if (newProxyUrl) {
+                this.toolboxProxyUrl = newProxyUrl;
+            }
+            if (newState) {
+                this.applyState(newState);
+            }
         }
         /**
          * Refreshes the Sandbox data from the API, but does not throw an error if the sandbox has been deleted.
@@ -1044,15 +1241,56 @@ let Sandbox = (() => {
          *
          * @returns {Promise<void>}
          */
+        /**
+         * @returns true when the refresh produced authoritative state (success, or 404
+         *          mapped to DESTROYED); false when a transient error was swallowed and
+         *          the cached state is stale.
+         */
         async refreshDataSafe() {
             try {
                 await this.refreshData();
+                return true;
             }
             catch (error) {
                 if (error instanceof DaytonaNotFoundError) {
-                    this.state = SandboxState.DESTROYED;
+                    this.applyState(SandboxState.DESTROYED);
+                    return true;
                 }
+                // Other errors are deliberately swallowed (parity with main): transient
+                // failures (e.g. 502) mid-poll must not abort stop()/delete() waits.
+                return false;
+            }
+        }
+        applyState(newState) {
+            if (newState === this.state) {
+                return;
+            }
+            this.state = newState;
+            for (const waiter of [...this.stateWaiters]) {
+                this.checkStateWaiter(waiter, this.state);
+            }
+        }
+        checkStateWaiter(waiter, state) {
+            if (!state) {
+                return false;
+            }
+            if (waiter.targetStates.has(state)) {
+                waiter.resolve(state);
+                return true;
+            }
+            if (waiter.errorStates.has(state)) {
+                const errorMessageFn = this.stateWaiterErrorMessageFns.get(waiter);
+                waiter.reject(new DaytonaError(errorMessageFn ? errorMessageFn(state) : `Sandbox ${this.id} failed with state: ${state}`));
+                return true;
+            }
+            return false;
+        }
+        removeStateWaiter(waiter) {
+            const index = this.stateWaiters.indexOf(waiter);
+            if (index !== -1) {
+                this.stateWaiters.splice(index, 1);
             }
+            this.stateWaiterErrorMessageFns.delete(waiter);
         }
     };
 })();