Reposition sandbox messaging from ephemeral to persistent-first (#137)

beran-t · web-flow · commit c5f04f6fe1b6 · 2026-03-02T19:42:34.000+01:00
* Reposition sandbox messaging from ephemeral to persistent-first

Replace ephemeral language (spin up, disposable, destroyed automatically,
alive for 5 minutes) across 15 doc pages with persistent-first framing.
Sandboxes are now described as long-running by default with auto-pause,
while preserving isolation, security, and scalability messaging.

* Remove persistence beta labels and update API methods to GA

Persistence is no longer in beta. Remove all beta notes, rename
betaPause/beta_pause to pause, betaCreate/beta_create to Sandbox.create,
and rename "Limitations while in beta" to "Limitations".

* Restore beta SDK method names (betaPause, betaCreate)

The previous commit incorrectly renamed the SDK methods. The beta
labels/notes in the docs are removed but the actual API methods
(betaPause, beta_pause, betaCreate, beta_create) are still the
current SDK surface.

* Clarify auto-pause triggers on timeout expiry, not idle detection

* Align lifecycle page with timeout-expiry framing

* Use Note callout instead of Info on sandbox lifecycle page
diff --git a/docs.mdx b/docs.mdx
@@ -10,7 +10,7 @@ import { Quickstart } from '/snippets/Quickstart.jsx';
 
 E2B provides isolated sandboxes that let agents safely execute code, process data, and run tools. Our SDKs make it easy to start and manage these environments.
 
-Spin up a sandbox and run code in a few lines:
+Start a sandbox and run code in a few lines:
 
 <CodeGroup>
 ```bash JavaScript & TypeScript
@@ -50,7 +50,7 @@ A quick overview of the core building blocks you'll interact with when using E2B
 
 The documentation is split into three main sections:
 
-- [**Quickstart**](#quickstart) — Step-by-step tutorials that walk you through spinning up your first E2B sandboxes.
+- [**Quickstart**](#quickstart) — Step-by-step tutorials that walk you through creating your first E2B sandboxes.
 
 - [**Examples**](#examples) — In-depth tutorials focused on specific use cases. Pick the topics that match what you're building.
 
diff --git a/docs/agents/amp.mdx b/docs/agents/amp.mdx
@@ -8,7 +8,7 @@ icon: "/images/icons/amp.svg"
 
 ## CLI
 
-Spin up a sandbox with the [E2B CLI](/docs/cli).
+Create a sandbox with the [E2B CLI](/docs/cli).
 
 ```bash
 e2b sbx create amp
diff --git a/docs/agents/claude-code.mdx b/docs/agents/claude-code.mdx
@@ -8,7 +8,7 @@ icon: "/images/icons/claude-code.svg"
 
 ## CLI
 
-Spin up a sandbox with the [E2B CLI](/docs/cli).
+Create a sandbox with the [E2B CLI](/docs/cli).
 
 ```bash
 e2b sbx create claude
diff --git a/docs/agents/codex.mdx b/docs/agents/codex.mdx
@@ -8,7 +8,7 @@ icon: "/images/icons/codex.svg"
 
 ## CLI
 
-Spin up a sandbox with the [E2B CLI](/docs/cli).
+Create a sandbox with the [E2B CLI](/docs/cli).
 
 ```bash
 e2b sbx create codex
diff --git a/docs/agents/openclaw.mdx b/docs/agents/openclaw.mdx
@@ -8,7 +8,7 @@ icon: "/images/icons/openclaw.svg"
 
 ## CLI
 
-Spin up a sandbox with the [E2B CLI](/docs/cli).
+Create a sandbox with the [E2B CLI](/docs/cli).
 
 ```bash
 e2b sbx create openclaw
diff --git a/docs/agents/opencode.mdx b/docs/agents/opencode.mdx
@@ -8,7 +8,7 @@ icon: "/images/icons/opencode.svg"
 
 ## CLI
 
-Spin up a sandbox with the [E2B CLI](/docs/cli).
+Create a sandbox with the [E2B CLI](/docs/cli).
 
 ```bash
 e2b sbx create opencode
diff --git a/docs/billing.mdx b/docs/billing.mdx
@@ -92,10 +92,10 @@ Check your usage and costs in the [dashboard usage tab](https://e2b.dev/dashboar
   </Accordion>
 
   <Accordion title="How do I optimize costs?">
-    - **Always kill sandboxes when done** - Use `sbx.kill()` to stop billing immediately
-    - **Enable autopause** - Automatically pause sandboxes after a period of inactivity to stop billing while preserving state
+    - **Enable auto-pause** - Automatically pause sandboxes after a period of inactivity to stop billing while preserving state
+    - **Pause sandboxes when idle** - Use `sbx.pause()` to stop billing while keeping state available for later
+    - **Kill sandboxes you no longer need** - Use `sbx.kill()` to stop billing and release resources permanently
     - **Allocate only what you need** - Start with default resources (2 vCPU, 1 GB RAM) and increase only if necessary
-    - **Implement automatic timeouts** - Set max session lengths to prevent forgotten sandboxes from running
     - **Monitor actively running sandboxes** - Use the [CLI](/docs/cli/list-sandboxes) or [dashboard](https://e2b.dev/dashboard?tab=usage) to track active sandboxes
     - **Use lifecycle events** - Set up [webhooks](/docs/sandbox/lifecycle-events-webhooks) to get notified when sandboxes are created
   </Accordion>
diff --git a/docs/cli/connect-to-sandbox.mdx b/docs/cli/connect-to-sandbox.mdx
@@ -12,4 +12,4 @@ e2b sandbox connect <sandbox-id>
 
 Unlike the `create` command, `connect` does not kill the sandbox when you disconnect. When you exit the terminal, only your terminal session is closed—the sandbox continues running.
 
-Once connected, you can inspect the sandbox filesystem and processes to debug or experiment, or use it as a disposable environment for running agents instead of your local computer.
+Once connected, you can inspect the sandbox filesystem and processes to debug or experiment, or use it as a dedicated environment for running agents instead of your local computer.
diff --git a/docs/cli/create-sandbox.mdx b/docs/cli/create-sandbox.mdx
@@ -22,4 +22,4 @@ This will:
 3. Keep the sandbox alive while you're connected
 4. Automatically kill the sandbox when you exit the terminal
 
-Once connected, you can inspect the sandbox filesystem and processes to debug or experiment, or use it as a disposable environment for running agents instead of your local computer.
+Once connected, you can inspect the sandbox filesystem and processes to debug or experiment, or use it as a dedicated environment for running agents instead of your local computer.
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
@@ -35,7 +35,7 @@ We'll write the minimal code for starting Sandbox, executing Python inside it an
 import 'dotenv/config'
 import { Sandbox } from '@e2b/code-interpreter'
 
-const sbx = await Sandbox.create() // By default the sandbox is alive for 5 minutes
+const sbx = await Sandbox.create() // Creates a persistent sandbox session
 const execution = await sbx.runCode('print("hello world")') // Execute Python inside the sandbox
 console.log(execution.logs)
 
@@ -48,7 +48,7 @@ from dotenv import load_dotenv
 load_dotenv()
 from e2b_code_interpreter import Sandbox
 
-sbx = Sandbox.create() # By default the sandbox is alive for 5 minutes
+sbx = Sandbox.create() # Creates a persistent sandbox session
 execution = sbx.run_code("print('hello world')") # Execute Python inside the sandbox
 print(execution.logs)
 
diff --git a/docs/sandbox.mdx b/docs/sandbox.mdx
@@ -3,16 +3,11 @@ title: "Sandbox lifecycle"
 sidebarTitle: Lifecycle
 ---
 
-When you start the sandbox, it stays alive for 5 minutes by default but you can change it by passing the `timeout` parameter.
-After the time passes, the sandbox will be automatically shutdown.
+Sandboxes stay running as long as you need them. When their timeout expires, they automatically pause to save resources — preserving their full state so you can resume at any time. You can also configure an explicit timeout or shut down a sandbox manually.
 
-<Warning>
-The maximum time sandbox can be kept running without being paused is 
-- 24 hours on the Pro Tier
-- 1 hour on the Base Tier
-
-For more details, please refer to [sandbox persistance page](/docs/sandbox/persistence#limitations-while-in-beta).
-</Warning>
+<Note>
+Sandboxes can run continuously for up to 24 hours (Pro) or 1 hour (Base). For longer workloads, use [pause and resume](/docs/sandbox/persistence) — pausing resets the runtime window, and your sandbox's full state is preserved indefinitely.
+</Note>
 
 <CodeGroup>
 ```js JavaScript & TypeScript highlight={6}
diff --git a/docs/sandbox/persistence.mdx b/docs/sandbox/persistence.mdx
@@ -3,12 +3,6 @@ title: "Sandbox persistence"
 sidebarTitle: Persistence
 ---
 
-<Note>
-Sandbox persistence is currently in public beta:
-1. Consider [some limitations](#limitations-while-in-beta).
-2. The persistence is free for all users during the beta.
-</Note>
-
 The sandbox persistence allows you to pause your sandbox and resume it later from the same state it was in when you paused it.
 
 This includes not only state of the sandbox's filesystem but also the sandbox's memory. This means all running processes, loaded variables, data, etc.
@@ -65,7 +59,7 @@ from e2b_code_interpreter import Sandbox
 sandbox = Sandbox.create()  # Starts in Running state
 
 # Pause the sandbox
-sandbox.betaPause()  # Running → Paused
+sandbox.beta_pause()  # Running → Paused
 
 # Resume the sandbox
 sandbox.connect()  # Running/Paused → Running
@@ -99,7 +93,7 @@ print('Sandbox created', sbx.sandbox_id)
 # Pause the sandbox
 # You can save the sandbox ID in your database to resume the sandbox later
 sbx.beta_pause()
-print('Sandbox paused', sbx.sandbox_id) 
+print('Sandbox paused', sbx.sandbox_id)
 ```
 </CodeGroup>
 
@@ -215,9 +209,7 @@ Sandbox.kill(sbx.sandbox_id)
 </CodeGroup>
 
 ## Sandbox's timeout
-When you connect to a sandbox, the sandbox's timeout is reset to the default timeout of an E2B sandbox - 5 minutes.
-
-You can pass a custom timeout to the `Sandbox.connect()`/`Sandbox.connect()` method like this:
+When you connect to a sandbox, the inactivity timeout resets. The default is 5 minutes, but you can pass a custom timeout to the `Sandbox.connect()` method:
 
 <CodeGroup>
 ```js JavaScript & TypeScript
@@ -233,11 +225,9 @@ sbx = Sandbox.connect(sandbox_id, timeout=60) # 60 seconds
 </CodeGroup>
 
 
-### Auto-pause (beta)
+### Auto-pause
 
-**Note: Auto-pause is currently in beta and available through `Sandbox.betaCreate()`/`Sandbox.beta_create()` method.**
-
-Sandboxes can now automatically pause after they time out. When a sandbox is paused, it stops consuming compute but preserves its state. The default inactivity timeout is 10 minutes. You can change the timeout by passing the `timeoutMs`/`timeout` parameter to the `Sandbox.connect()`/`Sandbox.connect()` method.
+Sandboxes automatically pause when their timeout expires, preserving their full state instead of shutting down. You can resume at any time from exactly where you left off. The default timeout is 10 minutes — configure it with the `timeoutMs`/`timeout` parameter.
 
 <CodeGroup>
 ```js JavaScript & TypeScript
@@ -252,7 +242,7 @@ const sandbox = await Sandbox.betaCreate({
 ```python Python
 from e2b_code_interpreter import Sandbox
 
-# Create sandbox with auto-pause enabled (Beta)
+# Create sandbox with auto-pause enabled
 sandbox = Sandbox.beta_create(
     auto_pause=True,  # Auto-pause after the sandbox times out
     timeout=10 * 60, # Optional: change the default timeout (10 minutes)
@@ -268,15 +258,15 @@ If you `.kill()` the sandbox, it will be permanently deleted and you won't be ab
 ```js JavaScript & TypeScript
 import { Sandbox } from '@e2b/code-interpreter'
 
-// Create sandbox with auto-pause enabled (Beta)
+// Create sandbox with auto-pause enabled
 const sandbox = await Sandbox.betaCreate({
     autoPause: true  // Auto-pause after the sandbox times out
 })
 ```
 ```python Python
 from e2b_code_interpreter import Sandbox
 
-# Create sandbox with auto-pause enabled (Beta)
+# Create sandbox with auto-pause enabled
 sandbox = Sandbox.beta_create(
     auto_pause=True  # Auto-pause after the sandbox times out
 )
@@ -288,7 +278,7 @@ If you have a service (for example a server) running inside your sandbox and you
 If you resume the sandbox, the service will be accessible again but you need to connect clients again.
 
 
-## Limitations while in beta
+## Limitations
 
 ### Pause and resume performance
 - Pausing a sandbox takes approximately **4 seconds per 1 GiB of RAM**
diff --git a/docs/sandbox/pty.mdx b/docs/sandbox/pty.mdx
@@ -62,9 +62,7 @@ The PTY runs an interactive bash shell with `TERM=xterm-256color`, which support
 
 ## Timeout
 
-By default, PTY sessions have a **60-second timeout** which limits the total duration of the session. When the timeout is reached, the connection to the PTY session will be closed regardless of activity.
-
-For long-running sessions, set `timeoutMs: 0` (JavaScript) or `timeout=0` (Python) to disable the timeout.
+PTY sessions have a configurable timeout that controls the session duration. The default is 60 seconds. For interactive or long-running sessions, set `timeoutMs: 0` (JavaScript) or `timeout=0` (Python) to keep the session open indefinitely.
 
 <CodeGroup>
 ```js JavaScript & TypeScript
@@ -76,7 +74,7 @@ const terminal = await sandbox.pty.create({
   cols: 80,
   rows: 24,
   onData: (data) => process.stdout.write(data),
-  timeoutMs: 0,  // No timeout for long-running sessions
+  timeoutMs: 0,  // Keep the session open indefinitely
 })
 ```
 
@@ -91,7 +89,7 @@ terminal = sandbox.pty.create(
     cols=80,
     rows=24,
     on_data=lambda data: print(data.decode(), end=''),
-    timeout=0,  # No timeout for long-running sessions
+    timeout=0,  # Keep the session open indefinitely
 )
 ```
 </CodeGroup>
diff --git a/docs/use-cases/ci-cd.mdx b/docs/use-cases/ci-cd.mdx
@@ -4,7 +4,7 @@ description: "Run AI-powered code review, testing, and validation in secure E2B
 icon: "gears"
 ---
 
-CI/CD pipelines can use AI agents to review pull requests, generate tests, and validate code changes automatically. E2B sandboxes provide the secure, isolated execution environment where these agents can safely clone repositories, run untrusted code, and report results — all triggered by [GitHub Actions](https://docs.github.com/en/actions) on every pull request. Since each run gets a fresh sandbox, malicious or buggy PR code never touches your CI runner.
+CI/CD pipelines can use AI agents to review pull requests, generate tests, and validate code changes automatically. E2B sandboxes provide the secure, isolated execution environment where these agents can safely clone repositories, run untrusted code, and report results — all triggered by [GitHub Actions](https://docs.github.com/en/actions) on every pull request. Each run uses its own isolated sandbox, so malicious or buggy PR code never touches your CI runner.
 
 ## GitHub Actions workflow
 
@@ -260,11 +260,11 @@ print("Done")
 ```
 </CodeGroup>
 
-1. **Create sandbox** — `Sandbox.create()` spins up an isolated Linux environment with a 5-minute timeout
+1. **Create sandbox** — `Sandbox.create()` creates an isolated Linux environment for the review
 2. **Clone the PR** — `sandbox.git.clone()` checks out the PR branch using `x-access-token` + `GITHUB_TOKEN` for [authentication](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)
 3. **AI review** — runs `git diff` inside the sandbox, sends the output to an LLM — swap the model for any provider via [Connect LLMs](/docs/quickstart/connect-llms)
 4. **Run tests** — `commands.run()` streams output in real time and throws on failure (`CommandExitError` / `CommandExitException`)
-5. **Post results** — comments the review on the PR via the GitHub REST API, then destroys the sandbox
+5. **Post results** — comments the review on the PR via the GitHub REST API, then shuts down the sandbox
 
 ## Related guides
 
diff --git a/docs/use-cases/coding-agents.mdx b/docs/use-cases/coding-agents.mdx
@@ -13,15 +13,14 @@ Running coding agents directly on your machine or servers means giving AI-genera
 1. **Isolation** — agent-generated code runs in a secure sandbox, never touching your production systems or local machine
 2. **Full dev environment** — terminal, filesystem, git, and package managers are all available out of the box, so agents work like a developer would
 3. **Pre-built templates** — ready-made templates for popular agents get you started fast, and you can [build your own](/docs/template/quickstart) for any agent
-4. **Scalability** — spin up many sandboxes in parallel, each running its own agent on a separate task
+4. **Scalability** — run many sandboxes in parallel, each with its own agent on a separate task
 
 ## How It Works
 
 1. **Create a sandbox** — use a pre-built template or [build your own](/docs/template/quickstart) with any agent installed
 2. **Agent gets a full environment** — terminal, filesystem, git access, and any tools installed in the template
 3. **Agent works autonomously** — it reads the codebase, writes code, runs tests, and iterates until the task is done
-4. **Extract results** — pull out the git diff, structured output, or modified files via the SDK
-5. **Sandbox is cleaned up** — once the work is done, the sandbox is destroyed automatically. No lingering state or cleanup needed
+4. **Extract results** — pull out the git diff, structured output, or modified files via the SDK. The sandbox stays available for follow-up work, or you can pause it to pick up later
 
 ## Agent Examples
 

Original file line number	Diff line number	Diff line change
`@@ -12,4 +12,4 @@ e2b sandbox connect <sandbox-id>`
`12`	`12`
`13`	`13`	Unlike the `create` command, `connect` does not kill the sandbox when you disconnect. When you exit the terminal, only your terminal session is closed—the sandbox continues running.
`14`	`14`
`15`		`-Once connected, you can inspect the sandbox filesystem and processes to debug or experiment, or use it as a disposable environment for running agents instead of your local computer.`
	`15`	`+Once connected, you can inspect the sandbox filesystem and processes to debug or experiment, or use it as a dedicated environment for running agents instead of your local computer.`