docs: Extend sandbox management guide (#364)

Signed-off-by: James Murdza <[email protected]>

Author: jamesmurdza

public/llms-full.txt

@@ -1,5 +1,5 @@
 # Daytona Documentation v0.21.0
-# Generated on: 2025-06-17
+# Generated on: 2025-06-27
 
 
 title: API Keys
@@ -2240,38 +2240,48 @@ const daytona: Daytona = new Daytona({
 title: Sandbox Management
 
 import { Tabs, TabItem } from '@astrojs/starlight/components';
+import Image from 'astro/components/Image.astro';
 
 Sandboxes are isolated development environments managed by Daytona. This guide covers how to create, manage, and remove Sandboxes using the SDK.
 By default, Sandboxes auto-stop after 15 minutes of inactivity and use **1 vCPU**, **1GB RAM**, and **3GiB disk**.
 
+## Sandbox Lifecycle
+
+Throughout its lifecycle, a Daytona Sandbox can have several different states. The diagram below shows the states and possible transitions between them.
+
+<Fragment set:html={sandboxDiagram} />
+
+By default, sandboxes auto-stop after `15 minutes` of inactivity and auto-archive after `7 days` of being stopped.
+
 ## Creating Sandboxes
 
-Daytona SDK provides an option to create Sandboxes with default or custom configurations. You can specify the language, [Snapshot](/docs/snapshots), resources, environment variables, and volumes for the Sandbox.
-By default, the Sandboxes auto-stop after `15 minutes` of inactivity in order to save resources but the timeout can be increased.
+The Daytona SDK provides an option to create Sandboxes with default or custom configurations. You can specify the language, [Snapshot](/docs/snapshots), resources, environment variables, and volumes for the Sandbox.
+Running Sandboxes utilize CPU, memory, and disk storage. Every resource is charged per second of usage.
 
 :::tip
-If you want to prolong the auto-stop interval, you can use the `auto_stop_interval` parameter when creating a Sandbox. The parameter is measured in minutes.
-
-Setting the auto-stop interval parameter to `0` will disable the auto-stop functionality altogether and allow the sandbox to run indefinitely.
+If you want to prolong the auto-stop interval, you can [set the auto-stop interval parameter](/docs/sandbox-management#auto-stop-interval) when creating a Sandbox.
 :::
 
 ### Basic Sandbox Creation
 
-Daytona SDK provides methods to create Sandboxes with default configurations, specific languages, or custom labels using Python and TypeScript.
+The Daytona SDK provides methods to create Sandboxes with default configurations, specific languages, or custom labels using Python and TypeScript.
 
 ```python
 from daytona import Daytona, CreateSandboxFromSnapshotParams
 
 daytona = Daytona()
 
 # Create a basic Sandbox
+
 sandbox = daytona.create()
 
 # Create a Sandbox with specific language
+
 params = CreateSandboxFromSnapshotParams(language="python")
 sandbox = daytona.create(params)
 
 # Create a Sandbox with custom labels
+
 params = CreateSandboxFromSnapshotParams(labels={"SOME_LABEL": "my-label"})
 sandbox = daytona.create(params)
 
@@ -2293,6 +2303,8 @@ const sandbox = await daytona.create({ labels: { SOME_LABEL: 'my-label' } });
 ```
 
 
+ When Sandboxes are not actively used, it is recommended that they be stopped. This can be done manually [using the stop command](/docs/sandbox-management#stop-and-start-sandbox) or automatically by [setting the auto-stop interval](/docs/sandbox-management#auto-stop-and-auto-archive).
+
 :::note
 Daytona keeps a pool of warm Sandboxes using default Snapshots.  
 When available, your Sandbox will launch in milliseconds instead of cold-booting.
@@ -2312,6 +2324,7 @@ from daytona import Daytona, Resources, CreateSandboxFromImageParams, Image
 daytona = Daytona()
 
 # Create a Sandbox with custom resources
+
 resources = Resources(
     cpu=2,  # 2 CPU cores
     memory=4,  # 4GB RAM
@@ -2353,16 +2366,18 @@ All resource parameters are optional. If not specified, Daytona will use default
 
 ## Sandbox Information
 
-Daytona SDK provides methods to get information about a Sandbox, such as ID, root directory, and status using Python and TypeScript.
+The Daytona SDK provides methods to get information about a Sandbox, such as ID, root directory, and status using Python and TypeScript.
 
 ```python
 # Get Sandbox ID
 sandbox_id = sandbox.id
 
 # Get the root directory of the Sandbox user
+
 root_dir = sandbox.get_user_root_dir()
 
 # Get the Sandbox id, auto-stop interval and state
+
 print(sandbox.id)
 print(sandbox.auto_stop_interval)
 print(sandbox.state)
@@ -2385,22 +2400,76 @@ console.log(sandbox.state)
 
 To get the preview URL for a specific port, check out [Preview & Authentication](/docs/preview-and-authentication).
 
-## Stop & Remove Sandbox
+## Stop and Start Sandbox
 
-Daytona SDK provides methods to stop and delete Sandboxes using Python and TypeScript.
+The Daytona SDK provides methods to stop and start Sandboxes using Python and TypeScript.
+
+Stopped Sandboxes maintain filesystem persistence while their memory state is cleared. They incur only disk usage costs and can be started again when needed.
 
 ```python
+sandbox = daytona.create(CreateSandboxParams(language="python"))
+
 # Stop Sandbox
+
 sandbox.stop()
 
-# Delete Sandbox
-sandbox.delete()
+print(sandbox.id) # 7cd11133-96c1-4cc8-9baa-c757b8f8c916
+
+# The sandbox ID can later be used to find the sandbox and start it
+
+sandbox = daytona.find_one("7cd11133-96c1-4cc8-9baa-c757b8f8c916")
+
+# Start Sandbox
+
+sandbox.start()
 
 ```
 ```typescript
+const sandbox = await daytona.create({ language: 'typescript' });
+
 // Stop Sandbox
 await sandbox.stop();
 
+console.log(sandbox.id) // 7cd11133-96c1-4cc8-9baa-c757b8f8c916
+
+// The sandbox ID can later be used to find the sandbox and start it
+
+const sandbox = await daytona.findOne("7cd11133-96c1-4cc8-9baa-c757b8f8c916");
+
+// Start Sandbox
+await sandbox.start();
+```
+
+
+The stopped state should be used when the Sandbox is expected to be started again soon. Otherwise, it is recommended to stop and then archive the Sandbox to eliminate disk usage costs.
+
+## Archive Sandbox
+
+The Daytona SDK provides methods to archive Sandboxes using Python and TypeScript.
+
+When Sandboxes are archived, the entire filesystem state is moved to very cost-effective object storage, making it possible to keep Sandboxes available for an extended period.
+Starting an archived Sandbox takes more time than starting a stopped Sandbox, depending on its size.
+
+A Sandbox must be stopped before it can be archived, and can be started again in the same way as a stopped Sandbox.
+
+```python
+# Archive Sandbox
+sandbox.archive()
+```
+```typescript
+// Archive Sandbox
+await sandbox.archive();
+```
+
+## Delete Sandbox
+
+The Daytona SDK provides methods to delete Sandboxes using Python and TypeScript.
+
+```python
+# Delete Sandbox
+sandbox.delete()
+```
+```typescript
 // Delete Sandbox
 await sandbox.delete();
 ```
@@ -2435,13 +2504,22 @@ All sandboxes have been deleted
 
 :::
 
-## Sandbox States and Persistence
+## Auto-stop and Auto-archive
 
-Daytona keeps the filesystem in its entirety during the Sandbox lifecycle. The persistence functionality is built into the system, and nothing needs to be explicitly done from the user side.
+Daytona Sandboxes can be automatically stopped and archived based on user-defined intervals.
 
 ### Auto-stop Interval
 
-It is important to understand the Sandbox states to maintain cost-effectiveness. One useful built-in feature is the auto-stop interval. By default, it triggers after `15 minutes` of inactivity by stopping the Sandbox, but the number can changed to any value, including `0` which disables auto-stopping.
+The auto-stop interval parameter sets the amount of time after which a running Sandbox will be automatically stopped.
+
+The parameter can either be set to:
+
+- a time interval in minutes
+- `0`, which disables the auto-stop functionality, allowing the sandbox to run indefinitely
+
+If the parameter is not set, the default interval of `15` minutes will be used.
+
+:::
 
 ```python
 sandbox = daytona.create(CreateSandboxFromSnapshotParams(
@@ -2459,7 +2537,14 @@ const sandbox = await daytona.create({
 
 ### Auto-archive Interval
 
-Another useful built-in feature is the auto-archive interval. By default, it triggers after a Sandbox has been continuously stopped for `7 days` by archiving it, but the number can changed to any value, including `0` which means the maximum interval of `30 days` will be used.
+The auto-archive interval parameter sets the amount of time after which a continuously stopped Sandbox will be automatically archived.
+
+The parameter can either be set to:
+
+- a time interval in minutes
+- `0`, which means the maximum interval of `30 days` will be used
+
+If the parameter is not set, the default interval of `7 days` days will be used.
 
 ```python
 sandbox = daytona.create(CreateSandboxFromSnapshotParams(
@@ -2474,27 +2559,6 @@ const sandbox = await daytona.create({
 });
 ```
 
-A Daytona Sandbox can have three states during its lifecycle:
-
-### Running
-
-Running Sandboxes utilize CPU, memory, and disk storage. Every resource is charged per second of usage. When Sandboxes are not actively used, it is recommended that they be stopped. This can be done:
-
-- Manually using the stop command
-- Automatically by setting the autoStop interval
-
-### Stopped
-
-Stopped Sandboxes only utilize disk storage. They can be instantly started when needed. The stopped state should be used when the Sandbox is expected to be started again soon. Otherwise, it is recommended to archive the Sandbox to eliminate disk usage costs.
-
-### Archived
-
-When Sandboxes are archived, the entire filesystem state is moved to very cost-effective object storage, making it possible to keep Sandboxes available for an extended period.
-
-### Performance Considerations
-
-The tradeoff between archived and stopped states is that starting an archived Sandbox takes more time, depending on its size.
-
 title: Snapshots
 
 import { TabItem, Tabs } from '@astrojs/starlight/components'
@@ -2602,6 +2666,7 @@ from daytona import (
 daytona = Daytona()
 
 # Create a Snapshot with custom resources
+
 daytona.snapshot.create(
     CreateSnapshotParams(
         name="my-snapshot",
@@ -2616,11 +2681,13 @@ daytona.snapshot.create(
 )
 
 # Create a Sandbox with custom Snapshot
+
 sandbox = daytona.create(
     CreateSandboxFromSnapshotParams(
         snapshot="my-snapshot",
     )
 )
+
 ```
 ```typescript
 import { Daytona, Image } from "@daytonaio/sdk";

public/llms.txt

@@ -1,5 +1,5 @@
 # Daytona Documentation v0.21.0
-# Generated on: 2025-06-17
+# Generated on: 2025-06-27
 
 # Daytona
 
@@ -113,18 +113,17 @@
 - [Resource Limits](https://daytona.io/docs/process-code-execution#resource-limits)
 - [Region Selection](https://daytona.io/docs/regions)
 - [Sandbox Management](https://daytona.io/docs/sandbox-management)
+- [Sandbox Lifecycle](https://daytona.io/docs/sandbox-management#sandbox-lifecycle)
 - [Creating Sandboxes](https://daytona.io/docs/sandbox-management#creating-sandboxes)
 - [Basic Sandbox Creation](https://daytona.io/docs/sandbox-management#basic-sandbox-creation)
 - [Sandbox Resources](https://daytona.io/docs/sandbox-management#sandbox-resources)
 - [Sandbox Information](https://daytona.io/docs/sandbox-management#sandbox-information)
-- [Stop & Remove Sandbox](https://daytona.io/docs/sandbox-management#stop--remove-sandbox)
-- [Sandbox States and Persistence](https://daytona.io/docs/sandbox-management#sandbox-states-and-persistence)
+- [Stop and Start Sandbox](https://daytona.io/docs/sandbox-management#stop-and-start-sandbox)
+- [Archive Sandbox](https://daytona.io/docs/sandbox-management#archive-sandbox)
+- [Delete Sandbox](https://daytona.io/docs/sandbox-management#delete-sandbox)
+- [Auto-stop and Auto-archive](https://daytona.io/docs/sandbox-management#auto-stop-and-auto-archive)
 - [Auto-stop Interval](https://daytona.io/docs/sandbox-management#auto-stop-interval)
 - [Auto-archive Interval](https://daytona.io/docs/sandbox-management#auto-archive-interval)
-- [Running](https://daytona.io/docs/sandbox-management#running)
-- [Stopped](https://daytona.io/docs/sandbox-management#stopped)
-- [Archived](https://daytona.io/docs/sandbox-management#archived)
-- [Performance Considerations](https://daytona.io/docs/sandbox-management#performance-considerations)
 - [Snapshots](https://daytona.io/docs/snapshots)
 - [Creating Snapshots](https://daytona.io/docs/snapshots#creating-snapshots)
 - [Snapshot Resources](https://daytona.io/docs/snapshots#snapshot-resources)