Skip to main content

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). See 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).

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.

1. Install and configure​

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

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:

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). 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​

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). The command prints the sandbox's Linux kernel, and kill() ends the sandbox, which stops its billing.

The same in 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.

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.

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.

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).

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

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:

{
"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):

export SANDBOX_ID="<sandbox id>"

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

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:

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:

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:

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:

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