# Sandboxes quickstart

> Install the official E2B SDK, point it at Serenity Edge, create a sandbox, run a command, read its output, pause, resume and kill it, in Python, JavaScript and curl.

Source: https://docs.serenityedge.ai/docs/sandboxes/quickstart/

> **Private preview**
> 
> Sandboxes are in private preview, by invitation: they are enabled on request for existing Serenity Edge customers and partners (see [Access](https://docs.serenityedge.ai/docs/sandboxes/overview/#access)). See [Preview status](https://docs.serenityedge.ai/docs/sandboxes/overview/#preview-status) for what is and is not available.

This page sets up the official E2B SDK for Serenity Edge, runs a first command in a sandbox, and then goes through the whole lifecycle: create, run a command, pause, resume and kill. It does so with the E2B Python SDK, with the E2B JavaScript SDK and with curl.

You need a Serenity Edge API key whose account has Sandboxes enabled (see [Access](https://docs.serenityedge.ai/docs/sandboxes/overview/#access)).

> **Before you rely on a sandbox**
> 
> During the preview, paused sandboxes are not backed up and can be lost if the site's storage fails: keep anything you need outside the sandbox. Outbound traffic from a sandbox leaves from a shared address, which some websites limit or block. See [Preview status](https://docs.serenityedge.ai/docs/sandboxes/overview/#preview-status).

## 1\. Install and configure

Install the official E2B SDK. The preview is tested with version 2.63.0.

```bash
pip install e2b      # Python
npm install e2b      # JavaScript
```

The SDKs read the domain and the key from two environment variables. Set the domain to `serenityedge.ai` and the key to your Serenity Edge API key, the same key you use for inference:

```bash
export E2B_DOMAIN="serenityedge.ai"
export E2B_API_KEY="$SERENITY_EDGE_API_KEY"
```

The SDKs then call `https://api.serenityedge.ai`, the host of the inference API, to manage sandboxes, and send the key in the `X-API-Key` header. The API returns each sandbox with its own sandbox domain, and the SDKs reach the sandbox at `https://<port>-<sandbox id>.<sandbox domain>`: you do not set that domain (see [The sandbox domain](https://docs.serenityedge.ai/docs/sandboxes/overview/#the-sandbox-domain)). Nothing else in your code changes.

Every call is HTTPS, so your network needs to allow outbound HTTPS to `api.serenityedge.ai` and to the sandbox domain and its subdomains (`*.vlc1.serenitysandboxes.cloud` in the preview). There is no SSH access to sandboxes.

Keep the key secret. Do not embed it in client-side code or commit it to a repository, and do not pass it into a sandbox.

## 2\. Run a first command

```python
from e2b import Sandbox

sbx = Sandbox.create()
print(sbx.commands.run("uname -a").stdout)
sbx.kill()
```

`Sandbox.create()` with no arguments creates a sandbox from the public template, with 2 vCPUs, 2 GiB of memory and 20 GiB of free disk (see [Templates](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#templates)). The command prints the sandbox's Linux kernel, and `kill()` ends the sandbox, which stops its billing.

The same in JavaScript:

```javascript
import { Sandbox } from "e2b";

const sbx = await Sandbox.create();
console.log((await sbx.commands.run("uname -a")).stdout);
await sbx.kill();
```

## 3\. Run the whole lifecycle

The examples below also set a `timeout`: the number of seconds after which the sandbox is killed if you have not killed or paused it first. A sandbox is billed for every second it runs, so set a timeout that fits the task. See [Timeouts](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#timeouts).

### Python

```python
from e2b import Sandbox

# Create a sandbox from the public template that lives for at most 5 minutes.
sandbox = Sandbox.create(timeout=300, metadata={"purpose": "quickstart"})
print("created", sandbox.sandbox_id)

# Run a command and read its output.
result = sandbox.commands.run("echo hello from the sandbox")
print(result.stdout)

# Leave something on disk, then pause. Memory, disk and processes are kept.
sandbox.commands.run("echo kept across the pause > /home/user/note.txt")
sandbox.pause()

# Resume: connecting to a paused sandbox resumes it.
sandbox = Sandbox.connect(sandbox.sandbox_id, timeout=300)
print(sandbox.commands.run("cat /home/user/note.txt").stdout)

# Kill it. Billing stops here.
sandbox.kill()
```

### JavaScript

> **note**
> 
> The preview's end-to-end tests run with the Python SDK. This example makes the same calls with the JavaScript SDK.

```javascript
import { Sandbox } from "e2b";

// Create a sandbox from the public template that lives for at most 5 minutes.
let sandbox = await Sandbox.create({
  timeoutMs: 300_000,
  metadata: { purpose: "quickstart" },
});
console.log("created", sandbox.sandboxId);

// Run a command and read its output.
const result = await sandbox.commands.run("echo hello from the sandbox");
console.log(result.stdout);

// Leave something on disk, then pause. Memory, disk and processes are kept.
await sandbox.commands.run("echo kept across the pause > /home/user/note.txt");
await sandbox.pause();

// Resume: connecting to a paused sandbox resumes it.
sandbox = await Sandbox.connect(sandbox.sandboxId, { timeoutMs: 300_000 });
console.log((await sandbox.commands.run("cat /home/user/note.txt")).stdout);

// Kill it. Billing stops here.
await sandbox.kill();
```

### Commands that keep running

The SDKs end a command when its own timeout runs out, 60 seconds by default, even when it runs in the background. To keep a server or another long process running, start it in the background with the command timeout turned off: `timeout=0` in Python, `timeoutMs: 0` in JavaScript. See [Running commands and opening a terminal](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#running-commands-and-opening-a-terminal).

### curl

With curl you call the control part of the API, at `https://api.serenityedge.ai` on the E2B API's paths (not under `/v1`): create, read, pause, resume and kill. Running a command goes through the agent inside the sandbox, which speaks a streaming RPC protocol that the SDKs implement, so use an SDK for commands, files and a terminal (see [Running commands and opening a terminal](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#running-commands-and-opening-a-terminal)).

Create a sandbox. Over HTTP the template is required: `base` is the public template, the same one the SDKs use when you name none:

```bash
curl -sS -X POST "https://api.serenityedge.ai/sandboxes" \
  -H "X-API-Key: $E2B_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "base",
    "timeout": 300,
    "metadata": {"purpose": "quickstart"}
  }'
```

The answer is HTTP 201 with the sandbox id, its access tokens and its sandbox domain:

```json
{
  "sandboxID": "<sandbox id>",
  "envdAccessToken": "<token for commands and files>",
  "trafficAccessToken": "<token for the sandbox's ports>",
  "domain": "vlc1.serenitysandboxes.cloud"
}
```

The answer also has `alias`, `clientID`, `envdVersion` and `templateID`. The calls below need only the id, so keep it (the domain is for the sandbox's own ports; see [Sandbox ports](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#sandbox-ports)):

```bash
export SANDBOX_ID="<sandbox id>"
```

Read its state (`running` or `paused`), its size and when it expires:

```bash
curl -sS "https://api.serenityedge.ai/sandboxes/$SANDBOX_ID" \
  -H "X-API-Key: $E2B_API_KEY"
```

Pause it. The answer is HTTP 204 with no body:

```bash
curl -sS -X POST "https://api.serenityedge.ai/sandboxes/$SANDBOX_ID/pause" \
  -H "X-API-Key: $E2B_API_KEY"
```

Resume it by connecting to it, with a new timeout in seconds. The answer is HTTP 201 when the sandbox was resumed and HTTP 200 when it was already running:

```bash
curl -sS -X POST "https://api.serenityedge.ai/sandboxes/$SANDBOX_ID/connect" \
  -H "X-API-Key: $E2B_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout": 300}'
```

Kill it. The answer is HTTP 204 with no body:

```bash
curl -sS -X DELETE "https://api.serenityedge.ai/sandboxes/$SANDBOX_ID" \
  -H "X-API-Key: $E2B_API_KEY"
```

## 4\. Check that nothing is left running

A sandbox that you forget keeps running, and is billed, until its timeout. A paused sandbox is billed for its storage until you kill it or it expires after 30 days. List what your account has:

```bash
curl -sS "https://api.serenityedge.ai/v2/sandboxes?state=running,paused" \
  -H "X-API-Key: $E2B_API_KEY"
```

## What to read next

-   [API reference](https://docs.serenityedge.ai/docs/sandboxes/api-reference/): every supported endpoint and create field, the template, and the pause and resume rules.
-   [Running commands and opening a terminal](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#running-commands-and-opening-a-terminal): processes, files and an interactive terminal through the SDKs.
-   [Network access and security](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/): what a sandbox can reach (public websites and APIs over HTTP and HTTPS) and what it cannot.
-   [Errors](https://docs.serenityedge.ai/docs/sandboxes/errors/): what each status and `error_code` means and whether to retry.
-   [Pricing and usage](https://docs.serenityedge.ai/docs/sandboxes/pricing-and-usage/): what the lifecycle above costs.
