Sandbox Async - E2B Docs

SandboxApi

Python

class SandboxApi(SandboxApiBase)

list

Python

@classmethod
async def list(cls,
               api_key: Optional[str] = None,
               query: Optional[SandboxQuery] = None,
               domain: Optional[str] = None,
               debug: Optional[bool] = None,
               request_timeout: Optional[float] = None,
               headers: Optional[Dict[str, str]] = None,
               proxy: Optional[ProxyTypes] = None) -> List[ListedSandbox]

List all running sandboxes. Arguments:

api_key: API key to use for authentication, defaults to E2B_API_KEY environment variable
query: Filter the list of sandboxes, e.g. by metadata SandboxQuery(metadata={"key": "value"}), if there are multiple filters they are combined with AND.
domain: Domain to use for the request, only relevant for self-hosted environments
debug: Enable debug mode, all requested are then sent to localhost
request_timeout: Timeout for the request in seconds
headers: Additional headers to send with the request
proxy: Proxy to use for the request

Returns: List of running sandboxes

Filesystem

Python

class Filesystem()

Module for interacting with the filesystem in the sandbox.

read

Python

@overload
async def read(path: str,
               format: Literal["text"] = "text",
               user: Username = "user",
               request_timeout: Optional[float] = None) -> str

Read file content as a str. Arguments:

path: Path to the file
user: Run the operation as this user
format: Format of the file content—text by default
request_timeout: Timeout for the request in seconds

Returns: File content as a str

read

Python

@overload
async def read(path: str,
               format: Literal["bytes"],
               user: Username = "user",
               request_timeout: Optional[float] = None) -> bytearray

Read file content as a bytearray. Arguments:

path: Path to the file
user: Run the operation as this user
format: Format of the file content—bytes
request_timeout: Timeout for the request in seconds

Returns: File content as a bytearray

read

Python

@overload
async def read(
        path: str,
        format: Literal["stream"],
        user: Username = "user",
        request_timeout: Optional[float] = None) -> AsyncIterator[bytes]

Read file content as a AsyncIterator[bytes]. Arguments:

path: Path to the file
user: Run the operation as this user
format: Format of the file content—stream
request_timeout: Timeout for the request in seconds

Returns: File content as an AsyncIterator[bytes]

write

Python

@overload
async def write(path: str,
                data: Union[str, bytes, IO],
                user: Username = "user",
                request_timeout: Optional[float] = None) -> WriteInfo

Write content to a file on the path. Writing to a file that doesn’t exist creates the file. Writing to a file that already exists overwrites the file. Writing to a file at path that doesn’t exist creates the necessary directories. Arguments:

path: Path to the file
data: Data to write to the file, can be a str, bytes, or IO.
user: Run the operation as this user
request_timeout: Timeout for the request in seconds

Returns: Information about the written file

write

Python

@overload
async def write(files: List[WriteEntry],
                user: Optional[Username] = "user",
                request_timeout: Optional[float] = None) -> List[WriteInfo]

Writes multiple files. Arguments:

files: list of files to write
user: Run the operation as this user
request_timeout: Timeout for the request

Returns: Information about the written files

write

Python

async def write(
    path_or_files: Union[str, List[WriteEntry]],
    data_or_user: Union[str, bytes, IO, Username] = "user",
    user_or_request_timeout: Optional[Union[float, Username]] = None,
    request_timeout_or_none: Optional[float] = None
) -> Union[WriteInfo, List[WriteInfo]]

Writes content to a file on the path. When writing to a file that doesn’t exist, the file will get created. When writing to a file that already exists, the file will get overwritten. When writing to a file that’s in a directory that doesn’t exist, you’ll get an error.

list

Python

async def list(path: str,
               depth: Optional[int] = 1,
               user: Username = "user",
               request_timeout: Optional[float] = None) -> List[EntryInfo]

List entries in a directory. Arguments:

path: Path to the directory
depth: Depth of the directory to list
user: Run the operation as this user
request_timeout: Timeout for the request in seconds

Returns: List of entries in the directory

exists

Python

async def exists(path: str,
                 user: Username = "user",
                 request_timeout: Optional[float] = None) -> bool

Check if a file or a directory exists. Arguments:

path: Path to a file or a directory
user: Run the operation as this user
request_timeout: Timeout for the request in seconds

Returns: True if the file or directory exists, False otherwise

get_info

Python

async def get_info(path: str,
                   user: Username = "user",
                   request_timeout: Optional[float] = None) -> EntryInfo

Get information about a file or directory. Arguments:

path: Path to a file or a directory
user: Run the operation as this user
request_timeout: Timeout for the request in seconds

Returns: Information about the file or directory like name, type, and path

remove

Python

async def remove(path: str,
                 user: Username = "user",
                 request_timeout: Optional[float] = None) -> None

Remove a file or a directory. Arguments:

path: Path to a file or a directory
user: Run the operation as this user
request_timeout: Timeout for the request in seconds

rename

Python

async def rename(old_path: str,
                 new_path: str,
                 user: Username = "user",
                 request_timeout: Optional[float] = None) -> EntryInfo

Rename a file or directory. Arguments:

old_path: Path to the file or directory to rename
new_path: New path to the file or directory
user: Run the operation as this user
request_timeout: Timeout for the request in seconds

Returns: Information about the renamed file or directory

make_dir

Python

async def make_dir(path: str,
                   user: Username = "user",
                   request_timeout: Optional[float] = None) -> bool

Create a new directory and all directories along the way if needed on the specified path. Arguments:

path: Path to a new directory. For example ‘/dirA/dirB’ when creating ‘dirB’.
user: Run the operation as this user
request_timeout: Timeout for the request in seconds

Returns: True if the directory was created, False if the directory already exists

watch_dir

Python

async def watch_dir(path: str,
                    on_event: OutputHandler[FilesystemEvent],
                    on_exit: Optional[OutputHandler[Exception]] = None,
                    user: Username = "user",
                    request_timeout: Optional[float] = None,
                    timeout: Optional[float] = 60,
                    recursive: bool = False) -> AsyncWatchHandle

Watch directory for filesystem events. Arguments:

path: Path to a directory to watch
on_event: Callback to call on each event in the directory
on_exit: Callback to call when the watching ends
user: Run the operation as this user
request_timeout: Timeout for the request in seconds
timeout: Timeout for the watch operation in seconds. Using 0 will not limit the watch time
recursive: Watch directory recursively

Returns: AsyncWatchHandle object for stopping watching directory

AsyncWatchHandle

Python

class AsyncWatchHandle()

Handle for watching a directory in the sandbox filesystem. Use .stop() to stop watching the directory.

stop

Python

async def stop()

Stop watching the directory.

AsyncSandbox

Python

class AsyncSandbox(SandboxSetup, SandboxApi)

E2B cloud sandbox is a secure and isolated cloud environment. The sandbox allows you to:

Access Linux OS
Create, list, and delete files and directories
Run commands
Run isolated code
Access the internet

Check docs here. Use the AsyncSandbox.create() to create a new sandbox. Example:

Python

from e2b import AsyncSandbox

sandbox = await AsyncSandbox.create()

files

Python

@property
def files() -> Filesystem

Module for interacting with the sandbox filesystem.

commands

Python

@property
def commands() -> Commands

Module for running commands in the sandbox.

pty

Python

@property
def pty() -> Pty

Module for interacting with the sandbox pseudo-terminal.

sandbox_id

Python

@property
def sandbox_id() -> str

Unique identifier of the sandbox.

sandbox_domain

Python

@property
def sandbox_domain() -> str

Unique identifier of the sandbox.

init

Python

def __init__(**opts: Unpack[AsyncSandboxOpts])

Use AsyncSandbox.create() to create a new sandbox instead.

is_running

Python

async def is_running(request_timeout: Optional[float] = None) -> bool

Check if the sandbox is running. Arguments:

request_timeout: Timeout for the request in seconds

Returns: True if the sandbox is running, False otherwise Example

Python

sandbox = await AsyncSandbox.create()
await sandbox.is_running() # Returns True

await sandbox.kill()
await sandbox.is_running() # Returns False

create

Python

@classmethod
async def create(cls,
                 template: Optional[str] = None,
                 timeout: Optional[int] = None,
                 metadata: Optional[Dict[str, str]] = None,
                 envs: Optional[Dict[str, str]] = None,
                 api_key: Optional[str] = None,
                 domain: Optional[str] = None,
                 debug: Optional[bool] = None,
                 request_timeout: Optional[float] = None,
                 proxy: Optional[ProxyTypes] = None,
                 secure: Optional[bool] = None,
                 allow_internet_access: Optional[bool] = True)

Create a new sandbox. By default, the sandbox is created from the default base sandbox template. Arguments:

template: Sandbox template name or ID
timeout: Timeout for the sandbox in seconds, default to 300 seconds. Maximum time a sandbox can be kept alive is 24 hours (86_400 seconds) for Pro users and 1 hour (3_600 seconds) for Hobby users.
metadata: Custom metadata for the sandbox
envs: Custom environment variables for the sandbox
api_key: E2B API Key to use for authentication, defaults to E2B_API_KEY environment variable
request_timeout: Timeout for the request in seconds
proxy: Proxy to use for the request and for the requests made to the returned sandbox
secure: Envd is secured with access token and cannot be used without it
allow_internet_access: Allow sandbox to access the internet, defaults to True.

Returns: sandbox instance for the new sandbox Use this method instead of using the constructor to create a new sandbox.

connect

Python

@classmethod
async def connect(cls,
                  sandbox_id: str,
                  api_key: Optional[str] = None,
                  domain: Optional[str] = None,
                  debug: Optional[bool] = None,
                  proxy: Optional[ProxyTypes] = None)

Connect to an existing sandbox. With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). Arguments:

sandbox_id: Sandbox ID
api_key: E2B API Key to use for authentication, defaults to E2B_API_KEY environment variable
proxy: Proxy to use for the request and for the requests made to the returned sandbox

Returns: sandbox instance for the existing sandbox @example

Python

sandbox = await AsyncSandbox.create()
sandbox_id = sandbox.sandbox_id

same_sandbox = await AsyncSandbox.connect(sandbox_id)


### kill

```python Python
@overload
async def kill(request_timeout: Optional[float] = None) -> bool

Kill the sandbox. Arguments:

request_timeout: Timeout for the request in seconds

Returns: True if the sandbox was killed, False if the sandbox was not found

kill

Python

@overload
@staticmethod
async def kill(sandbox_id: str,
               api_key: Optional[str] = None,
               domain: Optional[str] = None,
               debug: Optional[bool] = None,
               request_timeout: Optional[float] = None,
               proxy: Optional[ProxyTypes] = None) -> bool

Kill the sandbox specified by sandbox ID. Arguments:

sandbox_id: Sandbox ID
api_key: E2B API Key to use for authentication, defaults to E2B_API_KEY environment variable
request_timeout: Timeout for the request in seconds
proxy: Proxy to use for the request

Returns: True if the sandbox was killed, False if the sandbox was not found

set_timeout

Python

@overload
async def set_timeout(timeout: int,
                      request_timeout: Optional[float] = None) -> None

Set the timeout of the sandbox. After the timeout expires the sandbox will be automatically killed. This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to .set_timeout. Maximum time a sandbox can be kept alive is 24 hours (86_400 seconds) for Pro users and 1 hour (3_600 seconds) for Hobby users. Arguments:

timeout: Timeout for the sandbox in seconds
request_timeout: Timeout for the request in seconds

set_timeout

Python

@overload
@staticmethod
async def set_timeout(sandbox_id: str,
                      timeout: int,
                      api_key: Optional[str] = None,
                      domain: Optional[str] = None,
                      debug: Optional[bool] = None,
                      request_timeout: Optional[float] = None,
                      proxy: Optional[ProxyTypes] = None) -> None

Set the timeout of the specified sandbox. After the timeout expires the sandbox will be automatically killed. This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to .set_timeout. Maximum time a sandbox can be kept alive is 24 hours (86_400 seconds) for Pro users and 1 hour (3_600 seconds) for Hobby users. Arguments:

sandbox_id: Sandbox ID
timeout: Timeout for the sandbox in seconds
request_timeout: Timeout for the request in seconds
proxy: Proxy to use for the request

get_info

Python

@overload
async def get_info(request_timeout: Optional[float] = None) -> SandboxInfo

Get sandbox information like sandbox ID, template, metadata, started at/end at date. Arguments:

request_timeout: Timeout for the request in seconds

Returns: Sandbox info

get_info

Python

@overload
@staticmethod
async def get_info(sandbox_id: str,
                   api_key: Optional[str] = None,
                   domain: Optional[str] = None,
                   debug: Optional[bool] = None,
                   request_timeout: Optional[float] = None,
                   headers: Optional[Dict[str, str]] = None,
                   proxy: Optional[ProxyTypes] = None) -> SandboxInfo

Get sandbox information like sandbox ID, template, metadata, started at/end at date. Arguments:

sandbox_id: Sandbox ID
api_key: E2B API Key to use for authentication, defaults to E2B_API_KEY environment variable
domain: E2B domain to use for authentication, defaults to E2B_DOMAIN environment variable
debug: Whether to use debug mode, defaults to E2B_DEBUG environment variable
request_timeout: Timeout for the request in seconds
headers: Custom headers to use for the request
proxy: Proxy to use for the request

Returns: Sandbox info

get_info

Python

@class_method_variant("_cls_get_info")
async def get_info(request_timeout: Optional[float] = None) -> SandboxInfo

Get sandbox information like sandbox ID, template, metadata, started at/end at date. Arguments:

request_timeout: Timeout for the request in seconds

Returns: Sandbox info

get_metrics

Python

@overload
async def get_metrics(
        start: Optional[datetime.datetime] = None,
        end: Optional[datetime.datetime] = None,
        request_timeout: Optional[float] = None) -> List[SandboxMetrics]

Get the metrics of the current sandbox. Arguments:

start: Start time for the metrics, defaults to the start of the sandbox
end: End time for the metrics, defaults to current time
request_timeout: Timeout for the request in seconds

Returns: List of sandbox metrics containing CPU, memory and disk usage information

get_metrics

Python

@overload
@staticmethod
async def get_metrics(
        sandbox_id: str,
        start: Optional[datetime.datetime] = None,
        end: Optional[datetime.datetime] = None,
        api_key: Optional[str] = None,
        domain: Optional[str] = None,
        debug: Optional[bool] = None,
        request_timeout: Optional[float] = None) -> List[SandboxMetrics]

Get the metrics of the sandbox specified by sandbox ID. Arguments:

sandbox_id: Sandbox ID
start: Start time for the metrics, defaults to the start of the sandbox
end: End time for the metrics, defaults to current time
api_key: E2B API Key to use for authentication, defaults to E2B_API_KEY environment variable
request_timeout: Timeout for the request in seconds

Returns: List of sandbox metrics containing CPU, memory and disk usage information

get_metrics

Python

@class_method_variant("_cls_get_metrics")
async def get_metrics(
        start: Optional[datetime.datetime] = None,
        end: Optional[datetime.datetime] = None,
        request_timeout: Optional[float] = None) -> List[SandboxMetrics]

Get the metrics of the current sandbox. Arguments:

start: Start time for the metrics, defaults to the start of the sandbox
end: End time for the metrics, defaults to current time
request_timeout: Timeout for the request in seconds

Returns: List of sandbox metrics containing CPU, memory and disk usage information

Pty

Python

class Pty()

Module for interacting with PTYs (pseudo-terminals) in the sandbox.

kill

Python

async def kill(pid: int, request_timeout: Optional[float] = None) -> bool

Kill PTY. Arguments:

pid: Process ID of the PTY
request_timeout: Timeout for the request in seconds

Returns: true if the PTY was killed, false if the PTY was not found

send_stdin

Python

async def send_stdin(pid: int,
                     data: bytes,
                     request_timeout: Optional[float] = None) -> None

Send input to a PTY. Arguments:

pid: Process ID of the PTY
data: Input data to send
request_timeout: Timeout for the request in seconds

create

Python

async def create(
        size: PtySize,
        on_data: OutputHandler[PtyOutput],
        user: Username = "user",
        cwd: Optional[str] = None,
        envs: Optional[Dict[str, str]] = None,
        timeout: Optional[float] = 60,
        request_timeout: Optional[float] = None) -> AsyncCommandHandle

Start a new PTY (pseudo-terminal). Arguments:

size: Size of the PTY
on_data: Callback to handle PTY data
user: User to use for the PTY
cwd: Working directory for the PTY
envs: Environment variables for the PTY
timeout: Timeout for the PTY in seconds
request_timeout: Timeout for the request in seconds

Returns: Handle to interact with the PTY

resize

Python

async def resize(pid: int,
                 size: PtySize,
                 request_timeout: Optional[float] = None)

Resize PTY. Call this when the terminal window is resized and the number of columns and rows has changed. Arguments:

pid: Process ID of the PTY
size: New size of the PTY
request_timeout: Timeout for the request in seconds

Commands

Python

class Commands()

Module for executing commands in the sandbox.

list

Python

async def list(request_timeout: Optional[float] = None) -> List[ProcessInfo]

Lists all running commands and PTY sessions. Arguments:

request_timeout: Timeout for the request in seconds

Returns: List of running commands and PTY sessions

kill

Python

async def kill(pid: int, request_timeout: Optional[float] = None) -> bool

Kill a running command specified by its process ID. It uses SIGKILL signal to kill the command. Arguments:

pid: Process ID of the command. You can get the list of processes using sandbox.commands.list()
request_timeout: Timeout for the request in seconds

Returns: True if the command was killed, False if the command was not found

send_stdin

Python

async def send_stdin(pid: int,
                     data: str,
                     request_timeout: Optional[float] = None) -> None

Send data to command stdin. :param pid Process ID of the command. You can get the list of processes using sandbox.commands.list(). :param data: Data to send to the command :param request_timeout: Timeout for the request in seconds

run

Python

@overload
async def run(cmd: str,
              background: Union[Literal[False], None] = None,
              envs: Optional[Dict[str, str]] = None,
              user: Username = "user",
              cwd: Optional[str] = None,
              on_stdout: Optional[OutputHandler[Stdout]] = None,
              on_stderr: Optional[OutputHandler[Stderr]] = None,
              timeout: Optional[float] = 60,
              request_timeout: Optional[float] = None) -> CommandResult

Start a new command and wait until it finishes executing. Arguments:

cmd: Command to execute
background: False if the command should be executed in the foreground, True if the command should be executed in the background
envs: Environment variables used for the command
user: User to run the command as
cwd: Working directory to run the command
on_stdout: Callback for command stdout output
on_stderr: Callback for command stderr output
timeout: Timeout for the command connection in seconds. Using 0 will not limit the command connection time
request_timeout: Timeout for the request in seconds

Returns: CommandResult result of the command execution

run

Python

@overload
async def run(cmd: str,
              background: Literal[True],
              envs: Optional[Dict[str, str]] = None,
              user: Username = "user",
              cwd: Optional[str] = None,
              on_stdout: Optional[OutputHandler[Stdout]] = None,
              on_stderr: Optional[OutputHandler[Stderr]] = None,
              timeout: Optional[float] = 60,
              request_timeout: Optional[float] = None) -> AsyncCommandHandle

Start a new command and return a handle to interact with it. Arguments:

cmd: Command to execute
background: False if the command should be executed in the foreground, True if the command should be executed in the background
envs: Environment variables used for the command
user: User to run the command as
cwd: Working directory to run the command
on_stdout: Callback for command stdout output
on_stderr: Callback for command stderr output
timeout: Timeout for the command connection in seconds. Using 0 will not limit the command connection time
request_timeout: Timeout for the request in seconds

Returns: AsyncCommandHandle handle to interact with the running command

connect

Python

async def connect(
        pid: int,
        timeout: Optional[float] = 60,
        request_timeout: Optional[float] = None,
        on_stdout: Optional[OutputHandler[Stdout]] = None,
        on_stderr: Optional[OutputHandler[Stderr]] = None
) -> AsyncCommandHandle

Connects to a running command. You can use AsyncCommandHandle.wait() to wait for the command to finish and get execution results. Arguments:

pid: Process ID of the command to connect to. You can get the list of processes using sandbox.commands.list()
request_timeout: Request timeout in seconds
timeout: Timeout for the command connection in seconds. Using 0 will not limit the command connection time
on_stdout: Callback for command stdout output
on_stderr: Callback for command stderr output

Returns: AsyncCommandHandle handle to interact with the running command

AsyncCommandHandle

Python

class AsyncCommandHandle()

Command execution handle. It provides methods for waiting for the command to finish, retrieving stdout/stderr, and killing the command.

pid

Python

@property
def pid()

Command process ID.

stdout

Python

@property
def stdout()

Command stdout output.

stderr

Python

@property
def stderr()

Command stderr output.

error

Python

@property
def error()

Command execution error message.

exit_code

Python

@property
def exit_code()

Command execution exit code. 0 if the command finished successfully. It is None if the command is still running.

disconnect

Python

async def disconnect() -> None

Disconnects from the command. The command is not killed, but SDK stops receiving events from the command. You can reconnect to the command using sandbox.commands.connect method.

wait

Python

async def wait() -> CommandResult

Wait for the command to finish and return the result. If the command exits with a non-zero exit code, it throws a CommandExitException. Returns: CommandResult result of command execution

kill

Python

async def kill() -> bool

Kills the command. It uses SIGKILL signal to kill the command Returns: True if the command was killed successfully, False if the command was not found

Python SDK v1.11.1

​SandboxApi

​list

​Filesystem

​read

​read

​read

​write

​write

​write

​list

​exists

​get_info

​remove

​rename

​make_dir

​watch_dir

​AsyncWatchHandle

​stop

​AsyncSandbox

​files

​commands

​pty

​sandbox_id

​sandbox_domain

​__init__

​is_running

​create

​connect

​kill

​set_timeout

​set_timeout

​get_info

​get_info

​get_info

​get_metrics

​get_metrics

​get_metrics

​Pty

​kill

​send_stdin

​create

​resize

​Commands

​list

​kill

​send_stdin

​run

​run

​connect

​AsyncCommandHandle

​pid

​stdout

​stderr

​error

​exit_code

​disconnect

​wait

​kill

SandboxApi

list

Filesystem

read

read

read

write

write

write

list

exists

get_info

remove

rename

make_dir

watch_dir

AsyncWatchHandle

stop

AsyncSandbox

files

commands

pty

sandbox_id

sandbox_domain

init

is_running

create

connect

kill

set_timeout

set_timeout

get_info

get_info

get_info

get_metrics

get_metrics

get_metrics

Pty

kill

send_stdin

create

resize

Commands

list

kill

send_stdin

run

run

connect

AsyncCommandHandle

pid

stdout

stderr

error

exit_code

disconnect

wait

kill