adjustments

Author: christianalfoni

packages/projects-docs/pages/sdk/core-concepts.mdx

@@ -51,7 +51,7 @@ Sandboxes have three states of persistence:
 
 By default, when a Sandbox is hibernated, a memory snapshot is created. This allows for near-instant resumes the next time the Sandbox is accessed—typically within 0.5–2 seconds.
 
-- Hibernated Sandboxes are stored on disk for up to 7 days.
+- Hibernated Sandboxes are stored on disk for up to 7 days
 - After 7 days, or if disk space is limited, Sandboxes may be archived to long-term storage.
 - Archived Sandboxes are slower to resume, but still retain their full state.
 
@@ -60,7 +60,7 @@ By default, when a Sandbox is hibernated, a memory snapshot is created. This all
 While advanced persistence controls are coming in future SDK versions, you can improve reliability and startup times today by following these best practices:
 
 - Persist workspace data to Git or a database.
-- Prefer deleting Sandboxes over hibernating when long inactivity is expected.
+- Prefer deleting Sandboxes over hibernating when longer inactivity is expected.
 - On resume, recreate the environment from a template and pull data from Git or your database.
 
 These steps reduce reliance on long-term VM snapshots and improve resume consistency—especially in high-scale or collaborative environments.
@@ -69,8 +69,6 @@ These steps reduce reliance on long-term VM snapshots and improve resume consist
 
 The Sandbox lifecycle defines how environments are created, used, paused, resumed, and eventually cleaned up. Users may interact with Sandboxes directly, or indirectly via agents (such as automation tools or connected services).
 
-Below are the key stages of the lifecycle and how to manage them effectively:
-
 📘 For detailed API usage, refer to [Lifecycle Management](./manage-sandboxes)
 
 ### Template creation
@@ -108,8 +106,8 @@ Below are the key stages of the lifecycle and how to manage them effectively:
 - The user or agent starts a new session on a previously hibernated Sandbox.
 - The Sandbox resumes using the SDK.
 - Resume times vary based on persistence:
-  - From memory: 0.5–2 seconds
-  - From disk: 5–20 seconds
+  - From memory/disk snapshot: 0.5–2 seconds
+  - From disk snapshot: 5–20 seconds
   - From archive: 20–60 seconds
 
 ### Deleting

packages/projects-docs/pages/sdk/create.mdx

@@ -50,22 +50,22 @@ const sandbox = await sdk.sandboxes.create({
     // What VM Tier to use for the Sandbox
     vmTier: VMTier.Micro,
 
-    // How quickly the sandbox should hibernate after inactivity. Set
-    // this field to the maximum 24 hours (See deprecation below)
-    hibernationTimeoutSeconds: 86400,
+    // How quickly the sandbox should hibernate after inactivity. Recommended
+    // setting is 24 hours
+    hibernationTimeoutSeconds: 300,
 
     // Configure if Sandbox should wake up automatically on HTTP
-    // or requests or WebSocket connections. Set both of these to `false`
-    // (See deprecation below)
+    // or requests or WebSocket connections. Recommended setting
+    // is false
     automaticWakeupConfig: {
-        http: false,
+        http: true,
         websocket: false
     }
 })
 ```
 
 <Callout type="warning">
-Both `hibernationTimeoutSeconds` and `wakeupConfig` have been deprecated. Manual lifecycle management is required to scale, control costs, and create a predictable user experience. These features will not be available in the next major version.
+Both `hibernationTimeoutSeconds` and `wakeupConfig` should be carefully evaluated. Manual lifecycle management is considered best practice and is required to scale, control costs, and create a predictable user experience.
 </Callout>
 
 Each Sandbox has the following properties, with information about its own instance:
@@ -85,13 +85,12 @@ const sandbox = await sdk.sandboxes.create({
 })
 ```
 
-Ensure the parent Sandbox is in a `HIBERNATED` state before performing this operation.
-
 <Callout type="warning">
-Depending on the state of the parent Sandbox:
+Be careful with the state of the parent Sandbox:
 
-- **RUNNING**: This creates what we call a "Live Fork", which is limited to 5. The created Sandboxes will share memory with the parent and can cause a degraded experience
-- **ARCHIVED**: The parent Sandbox first needs to be resumed, which can take 10-60 seconds, causing the creation to take a long time
+- **HIBERNATED**: It will be a fast fork of 1-3 seconds
+- **RUNNING**: This creates what we call a "Live Fork", which is limited to 5. The created Sandboxes will share memory with the parent and causes a degraded experience if excessively used
+- **ARCHIVED**: The parent Sandbox first needs to be resumed, which can take 20-60 seconds, causing the creation to take a long time
 
 </Callout>
 
@@ -105,12 +104,10 @@ There is also a `/project/sandbox` folder, but consider this deprecated. Use `/p
 
 The primary persistence mechanism is based on git with a local remote. This means the workspace is initialized with git automatically.
 
-<Callout type="warning">
-Running git commands in the workspace without setting a new remote will cause issues with persistence.
-</Callout>
-
 ### Using git in the root workspace
 
+Since the default persistence of a Sandbox is using git you should not run any git commands in the workspace unless you change the remote.
+
 ```bash
 # Remove the default local remote and add your own
 git remote remove origin

packages/projects-docs/pages/sdk/hibernate.mdx

@@ -7,7 +7,7 @@ import { Callout } from 'nextra-theme-docs'
 
 # Hibernate Sandboxes
 
-Hibernating a Sandbox allows you to stop its running costs and resume it at a later point. When hibernating the Sandbox it will produce a snapshot with memory and disk, but depending on health cluster and days passed change its state.
+Hibernating a Sandbox allows you to stop its running costs and resume it at a later point. When hibernating the Sandbox it will produce a snapshot with memory and disk, but depending on cluster load, and days passed, the persistence will change its state.
 
 | **State**   | **Resume Time** | **Description**                                   |
 | ----------- | --------------- | ------------------------------------------------- |

packages/projects-docs/pages/sdk/index.mdx

@@ -15,7 +15,7 @@ CodeSandbox SDK enables you to quickly create and run isolated sandboxes securel
 The SDK can be used to run concurrent VMs to support multiple use cases such as browser editors, AI agents, code interpretation and more.
 
 <Callout>
-We are soon to introduce **long term persistence**. Please read our [RFC](https://gist.github.com/christianalfoni/70335f989312484c8f348148aa2e166e) for planned deprecations and future roadmap.
+We are currently working on improvements to our infrastructure. Please read our [RFC](https://gist.github.com/christianalfoni/70335f989312484c8f348148aa2e166e) for planned deprecations and future roadmap. We would love your feedback!
 </Callout>
 
 ## Quickstart

packages/projects-docs/pages/sdk/manage-sandboxes.mdx

@@ -9,12 +9,16 @@ import { Callout } from 'nextra-theme-docs'
 
 Use your own persistence layer to track VM sessions and sandbox lifecycle states. This will give you the following benefits:
 
-- A request does not accidentally extend hibernation timeout
+- A request does not accidentally keep a Sandbox running
 - A webhook can be called from a process inside the Sandbox to control lifecycle
 - As hibernation is directly called, error management is straight forward
 - No **ux** vs **cost** tradeoff
 - Latency is reduced as session/db state determines state of Sandbox, preventing unecessary calls to `resume`
 
+<Callout>
+To adopt best practices set `hibernationTimeoutSeconds` to `86400` (24 hours) and `automaticWakeupConfig` to `false` when you create Sandboxes.
+</Callout>
+
 How you manage the resume/hibernate/delete part of the lifecycle depends on your use case. You might have user sessions, agent sessions or maybe sessions bound to accessing a process exposing a host. Regardless you want to `resume` the Sandbox when the session starts and `hibernate` or `delete` when the sessions ends.
 
 Examples of identifying lifecycles:
@@ -126,7 +130,7 @@ setInterval(async () => {
 
 ## Managed persistence example
 
-You can choose not to rely on our persistence at all. By using `delete` instead of `hibernate`, you minimize costs and maintain optimal control of Sandbox resumes.
+You can choose not to rely on our persistence at all. By using `delete`, instead of `hibernate`, you maintain optimal control of Sandbox resumes.
 
 When you want to stop using the Sandbox, push any changes to your database or Git. Then `delete` the Sandbox. When you want to resume, `create` a new Sandbox from the template and pull data back from your database or Git.