From beb4a0fb8cd887e8bf59e8db3cbddb4723e6189d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 10 Oct 2024 07:23:54 +0000 Subject: [PATCH] [skip ci] Release new SDK API reference doc versions --- .../v0.16.2-beta.52/filesystem/page.mdx | 2 +- .../python-sdk/v0.17.1/sandbox_async/page.mdx | 674 +++++++++--------- .../python-sdk/v0.17.1/sandbox_sync/page.mdx | 602 ++++++++-------- 3 files changed, 639 insertions(+), 639 deletions(-) diff --git a/apps/web/src/app/(docs)/docs/api-reference/js-sdk/v0.16.2-beta.52/filesystem/page.mdx b/apps/web/src/app/(docs)/docs/api-reference/js-sdk/v0.16.2-beta.52/filesystem/page.mdx index 4c2426ec8..6b20d4b01 100644 --- a/apps/web/src/app/(docs)/docs/api-reference/js-sdk/v0.16.2-beta.52/filesystem/page.mdx +++ b/apps/web/src/app/(docs)/docs/api-reference/js-sdk/v0.16.2-beta.52/filesystem/page.mdx @@ -305,7 +305,7 @@ sandbox/filesystem/index.ts:355 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. + When writing to a file that's in a directory that doesn't exist, the directory will get created. ###### Parameters diff --git a/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_async/page.mdx b/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_async/page.mdx index fead76b16..a7511b576 100644 --- a/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_async/page.mdx +++ b/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_async/page.mdx @@ -1,299 +1,329 @@ -## Filesystem + + +## AsyncSandbox ```python -class Filesystem() +class AsyncSandbox(SandboxSetup, SandboxApi) ``` -Manager for interacting with the filesystem in the sandbox. +E2B cloud sandbox gives your agent a full cloud development environment that's sandboxed. +That means: +- Access to Linux OS +- Using filesystem (create, list, and delete files and dirs) +- Run commands +- Sandboxed - you can run any code +- Access to the internet -#### read +Check usage docs - https://e2b.dev/docs/sandbox/overview -```python -async def read(path: str, - format: Literal["text", "bytes", "stream"] = "text", - user: Username = "user", - request_timeout: Optional[float] = None) -``` +These cloud sandboxes are meant to be used for agents. Like a sandboxed playgrounds, where the agent can do whatever it wants. -Reads a whole file content and returns it in requested format (text by default). +Use the `AsyncSandbox.create()` to create a new sandbox. -:param path: Path to the file -:param format: Format of the file content -:param user: Run the operation as this user -:param request_timeout: Timeout for the request -:return File content in requested format +**Example**: +```python +sandbox = await AsyncSandbox.create() +``` -#### write +#### files ```python -async def write(path: str, - data: Union[str, bytes, IO], - user: Username = "user", - request_timeout: Optional[float] = None) -> EntryInfo +@property +def files() -> Filesystem ``` -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. +Filesystem module for interacting with the sandbox's filesystem -**Arguments**: -- `path`: Path to the file -- `data`: Data to write to the file -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request +#### commands -**Returns**: +```python +@property +def commands() -> Process +``` -Information about the written file +Commands module for interacting with the sandbox's processes -#### list +#### pty ```python -async def list(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> List[EntryInfo] +@property +def pty() -> Pty ``` -Lists entries in a directory. +PTY module for interacting with the sandbox's pseudo-terminal. -**Arguments**: -- `path`: Path to the directory -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request +#### sandbox\_id -**Returns**: +```python +@property +def sandbox_id() -> str +``` -List of entries in the directory +Get the sandbox ID -#### exists +#### envd\_api\_url ```python -async def exists(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> bool +@property +def envd_api_url() -> str ``` -Checks if a file or a directory exists. +Get the sandbox API URL -:param path: Path to a file or a directory -:param user Run the operation as this user -:param request_timeout Timeout for the request +#### connection\_config +```python +@property +def connection_config() -> ConnectionConfig +``` + +Get the ConnectionConfig object -#### remove + +#### \_\_init\_\_ ```python -async def remove(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> None +def __init__(**opts: Unpack[AsyncSandboxOpts]) ``` -Removes a file or a directory. +Use `Sandbox.create()` instead. -**Arguments**: -- `path`: Path to a file or a directory -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request +#### is\_running + +```python +async def is_running(request_timeout: Optional[float] = None) -> bool +``` +Check if the sandbox is running. -#### rename +**Returns**: +`True` if the sandbox is running, `False` otherwise +Example ```python -async def rename(old_path: str, - new_path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> EntryInfo +sandbox = await AsyncSandbox.create() +await sandbox.is_running() # Returns True + +await sandbox.kill() +await sandbox.is_running() # Returns False ``` -Renames a file or directory from one path to another. -:param old_path Path to the file or directory to move -:param new_path Path to move the file or directory to -:param user Run the operation as this user -:param request_timeout Timeout for the request +#### create -:return: Information about the renamed file or directory +```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) +``` + +Creates a new sandbox. +This method creates a new sandbox in the async version, +you have to use this method instead of using the constructor. -#### make\_dir +#### connect ```python -async def make_dir(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> bool +@classmethod +async def connect(cls, + sandbox_id: str, + api_key: Optional[str] = None, + domain: Optional[str] = None, + debug: Optional[bool] = None) ``` -Creates a new directory and all directories along the way if needed on the specified path. +Connects to an existing Sandbox. **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 +- `sandbox_id`: Sandbox ID +- `api_key`: E2B API Key +- `domain`: E2B Domain (use only if you self-host E2B) +- `debug`: For developing purposes, uses a local sandbox **Returns**: -True if the directory was created, False if the directory already exists +Sandbox object +@example +```python +sandbox = await AsyncSandbox.create() +sandbox_id = sandbox.sandbox_id + +same_sandbox = await AsyncSandbox.connect(sandbox_id) -#### watch +#### kill ```python -async def watch(path: str, - on_event: OutputHandler[FilesystemEvent], - on_exit: Optional[OutputHandler[Exception]] = None, - user: Username = "user", - request_timeout: Optional[float] = None, - timeout: Optional[float] = 60) -> AsyncWatchHandle +@class_method_variant("_cls_kill") +async def kill(request_timeout: Optional[float] = None) -> bool ``` -Watches directory for filesystem events. +Kill the sandbox. **Arguments**: -- `path`: Path to a directory that will be watched -- `on_event`: Callback that will be called on each event -- `on_exit`: Callback that will be called when the watch is closed -- `user`: Run the operation as this user - `request_timeout`: Timeout for the request -- `timeout`: Timeout for the watch, after which the watch will be closed **Returns**: -Watcher handle - - +`True` if the sandbox was killed, `False` if the sandbox was not found -## AsyncWatchHandle +#### set\_timeout ```python -class AsyncWatchHandle() +@class_method_variant("_cls_set_timeout") +async def set_timeout(timeout: int, + request_timeout: Optional[float] = None) -> None ``` -Class representing the watch operation. It provides method to stop the watch operation. - +Set the sandbox's timeout, after which the sandbox will be automatically killed. -#### close +The sandbox can be kept alive for a maximum of 24 hours from the time of creation. +If you try to set the timeout to a period, which exceeds the maximum limit, the timeout will be set to the maximum limit. -```python -async def close() -``` +**Arguments**: -Stop watching the directory. +- `timeout`: Duration in milliseconds. Must be between 0 and 86400000 milliseconds (24 hours). +- `request_timeout`: Timeout for the request -## AsyncProcessHandle +## Process ```python -class AsyncProcessHandle() +class Process() ``` -Class representing a process. It provides methods for waiting and killing the process. +Manager for starting and interacting with processes in the sandbox. -#### pid +#### list ```python -@property -def pid() +async def list(request_timeout: Optional[float] = None) -> List[ProcessInfo] ``` -Get the process ID. +Lists all running processes. +**Arguments**: -#### stdout +- `request_timeout`: Request timeout -```python -@property -def stdout() -``` +**Returns**: -Stdout of the process. +List of running processes -#### stderr +#### kill ```python -@property -def stderr() +async def kill(pid: int, request_timeout: Optional[float] = None) -> bool ``` -Stderr of the process. +Kills a process. +**Arguments**: -#### error +- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. +- `request_timeout`: Request timeout -```python -@property -def error() -``` +**Returns**: -Error message of the process. It is `None` if the process is still running. +`True` if the process was killed, `False` if the process was not found -#### exit\_code +#### send\_stdin ```python -@property -def exit_code() +async def send_stdin(pid: int, + data: str, + request_timeout: Optional[float] = None) -> None ``` -Exit code of the process. It is `None` if the process is still running. - - -#### disconnect +Sends data to the stdin of a process. -```python -async def disconnect() -> None -``` +:param pid Process ID to send data to. You can get the list of processes using `sandbox.commands.list()`. +:param data: Data to send to the process +:param request_timeout: Request timeout -Disconnects from the process. It does not kill the process. It only stops receiving events from the process. -#### wait +#### run ```python -async def wait() -> ProcessResult +async def run(cmd: str, + background: Union[bool, 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) ``` -Waits for the process to finish and returns the result. - -If the process exits with a non-zero exit code, it throws a `ProcessExitException`. +Starts a new process and depending on the `background` parameter, waits for the process to finish or not. -**Returns**: +:param cmd Command to execute +:param background: + If `True`, the function will return a `ProcessHandle` object that can be used to interact with the process. + If `False`, the function will wait for the process to finish and return a `ProcessResult` object. +:param envs: Environment variables +:param user: User to run the process as +:param cwd: Working directory +:param on_stdout: Callback for stdout +:param on_stderr: Callback for stderr +:param timeout: Timeout for the maximum time the process is allowed to run +:param request_timeout: Timeout for the request +:return: `ProcessHandle` if `background` is `True`, `ProcessResult` if `background` is `False` -Process result -#### kill +#### connect ```python -async def kill() -> bool +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 +) -> AsyncProcessHandle ``` -Kills the process. +Connects to an existing process. -**Returns**: +**Arguments**: -Whether the process was killed successfully +- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. +- `timeout`: Timeout for the connection +- `request_timeout`: Request timeout +- `on_stdout`: Callback for stdout +- `on_stderr`: Callback for stderr @@ -391,329 +421,299 @@ Resizes a PTY process (changes the number of columns and rows in the terminal). -## Process - -```python -class Process() -``` - -Manager for starting and interacting with processes in the sandbox. - - -#### list +## AsyncProcessHandle ```python -async def list(request_timeout: Optional[float] = None) -> List[ProcessInfo] +class AsyncProcessHandle() ``` -Lists all running processes. - -**Arguments**: - -- `request_timeout`: Request timeout - -**Returns**: - -List of running processes +Class representing a process. It provides methods for waiting and killing the process. -#### kill +#### pid ```python -async def kill(pid: int, request_timeout: Optional[float] = None) -> bool +@property +def pid() ``` -Kills a process. - -**Arguments**: - -- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. -- `request_timeout`: Request timeout - -**Returns**: - -`True` if the process was killed, `False` if the process was not found +Get the process ID. -#### send\_stdin +#### stdout ```python -async def send_stdin(pid: int, - data: str, - request_timeout: Optional[float] = None) -> None +@property +def stdout() ``` -Sends data to the stdin of a process. - -:param pid Process ID to send data to. You can get the list of processes using `sandbox.commands.list()`. -:param data: Data to send to the process -:param request_timeout: Request timeout - +Stdout of the process. -#### run +#### stderr ```python -async def run(cmd: str, - background: Union[bool, 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) +@property +def stderr() ``` -Starts a new process and depending on the `background` parameter, waits for the process to finish or not. - -:param cmd Command to execute -:param background: - If `True`, the function will return a `ProcessHandle` object that can be used to interact with the process. - If `False`, the function will wait for the process to finish and return a `ProcessResult` object. -:param envs: Environment variables -:param user: User to run the process as -:param cwd: Working directory -:param on_stdout: Callback for stdout -:param on_stderr: Callback for stderr -:param timeout: Timeout for the maximum time the process is allowed to run -:param request_timeout: Timeout for the request -:return: `ProcessHandle` if `background` is `True`, `ProcessResult` if `background` is `False` - +Stderr of the process. -#### connect +#### error ```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 -) -> AsyncProcessHandle +@property +def error() ``` -Connects to an existing process. +Error message of the process. It is `None` if the process is still running. -**Arguments**: -- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. -- `timeout`: Timeout for the connection -- `request_timeout`: Request timeout -- `on_stdout`: Callback for stdout -- `on_stderr`: Callback for stderr +#### exit\_code +```python +@property +def exit_code() +``` +Exit code of the process. It is `None` if the process is still running. +#### disconnect +```python +async def disconnect() -> None +``` +Disconnects from the process. It does not kill the process. It only stops receiving events from the process. -## AsyncSandbox +#### wait ```python -class AsyncSandbox(SandboxSetup, SandboxApi) +async def wait() -> ProcessResult ``` -E2B cloud sandbox gives your agent a full cloud development environment that's sandboxed. +Waits for the process to finish and returns the result. -That means: -- Access to Linux OS -- Using filesystem (create, list, and delete files and dirs) -- Run commands -- Sandboxed - you can run any code -- Access to the internet +If the process exits with a non-zero exit code, it throws a `ProcessExitException`. -Check usage docs - https://e2b.dev/docs/sandbox/overview +**Returns**: -These cloud sandboxes are meant to be used for agents. Like a sandboxed playgrounds, where the agent can do whatever it wants. +Process result -Use the `AsyncSandbox.create()` to create a new sandbox. -**Example**: +#### kill ```python -sandbox = await AsyncSandbox.create() +async def kill() -> bool ``` +Kills the process. -#### files +**Returns**: -```python -@property -def files() -> Filesystem -``` +Whether the process was killed successfully -Filesystem module for interacting with the sandbox's filesystem -#### commands + + + +## AsyncWatchHandle ```python -@property -def commands() -> Process +class AsyncWatchHandle() ``` -Commands module for interacting with the sandbox's processes +Class representing the watch operation. It provides method to stop the watch operation. -#### pty +#### close ```python -@property -def pty() -> Pty +async def close() ``` -PTY module for interacting with the sandbox's pseudo-terminal. +Stop watching the directory. -#### sandbox\_id + + +## Filesystem ```python -@property -def sandbox_id() -> str +class Filesystem() ``` -Get the sandbox ID +Manager for interacting with the filesystem in the sandbox. -#### envd\_api\_url +#### read ```python -@property -def envd_api_url() -> str +async def read(path: str, + format: Literal["text", "bytes", "stream"] = "text", + user: Username = "user", + request_timeout: Optional[float] = None) ``` -Get the sandbox API URL +Reads a whole file content and returns it in requested format (text by default). +:param path: Path to the file +:param format: Format of the file content +:param user: Run the operation as this user +:param request_timeout: Timeout for the request +:return File content in requested format -#### connection\_config + + +#### write ```python -@property -def connection_config() -> ConnectionConfig +async def write(path: str, + data: Union[str, bytes, IO], + user: Username = "user", + request_timeout: Optional[float] = None) -> EntryInfo ``` -Get the ConnectionConfig object +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, the directory will get created. -#### \_\_init\_\_ +**Arguments**: -```python -def __init__(**opts: Unpack[AsyncSandboxOpts]) -``` +- `path`: Path to the file +- `data`: Data to write to the file +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request -Use `Sandbox.create()` instead. +**Returns**: +Information about the written file -#### is\_running + +#### list ```python -async def is_running(request_timeout: Optional[float] = None) -> bool +async def list(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> List[EntryInfo] ``` -Check if the sandbox is running. +Lists entries in a directory. -**Returns**: +**Arguments**: -`True` if the sandbox is running, `False` otherwise -Example -```python -sandbox = await AsyncSandbox.create() -await sandbox.is_running() # Returns True +- `path`: Path to the directory +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request -await sandbox.kill() -await sandbox.is_running() # Returns False -``` +**Returns**: +List of entries in the directory -#### create + +#### exists ```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) +async def exists(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> bool ``` -Creates a new sandbox. +Checks if a file or a directory exists. -This method creates a new sandbox in the async version, -you have to use this method instead of using the constructor. +:param path: Path to a file or a directory +:param user Run the operation as this user +:param request_timeout Timeout for the request -#### connect + +#### remove ```python -@classmethod -async def connect(cls, - sandbox_id: str, - api_key: Optional[str] = None, - domain: Optional[str] = None, - debug: Optional[bool] = None) +async def remove(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> None ``` -Connects to an existing Sandbox. +Removes a file or a directory. **Arguments**: -- `sandbox_id`: Sandbox ID -- `api_key`: E2B API Key -- `domain`: E2B Domain (use only if you self-host E2B) -- `debug`: For developing purposes, uses a local sandbox +- `path`: Path to a file or a directory +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request -**Returns**: -Sandbox object -@example +#### rename + ```python -sandbox = await AsyncSandbox.create() -sandbox_id = sandbox.sandbox_id +async def rename(old_path: str, + new_path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> EntryInfo +``` -same_sandbox = await AsyncSandbox.connect(sandbox_id) +Renames a file or directory from one path to another. + +:param old_path Path to the file or directory to move +:param new_path Path to move the file or directory to +:param user Run the operation as this user +:param request_timeout Timeout for the request +:return: Information about the renamed file or directory -#### kill + + +#### make\_dir ```python -@class_method_variant("_cls_kill") -async def kill(request_timeout: Optional[float] = None) -> bool +async def make_dir(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> bool ``` -Kill the sandbox. +Creates 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 **Returns**: -`True` if the sandbox was killed, `False` if the sandbox was not found +True if the directory was created, False if the directory already exists -#### set\_timeout +#### watch ```python -@class_method_variant("_cls_set_timeout") -async def set_timeout(timeout: int, - request_timeout: Optional[float] = None) -> None +async def watch(path: str, + on_event: OutputHandler[FilesystemEvent], + on_exit: Optional[OutputHandler[Exception]] = None, + user: Username = "user", + request_timeout: Optional[float] = None, + timeout: Optional[float] = 60) -> AsyncWatchHandle ``` -Set the sandbox's timeout, after which the sandbox will be automatically killed. - -The sandbox can be kept alive for a maximum of 24 hours from the time of creation. -If you try to set the timeout to a period, which exceeds the maximum limit, the timeout will be set to the maximum limit. +Watches directory for filesystem events. **Arguments**: -- `timeout`: Duration in milliseconds. Must be between 0 and 86400000 milliseconds (24 hours). +- `path`: Path to a directory that will be watched +- `on_event`: Callback that will be called on each event +- `on_exit`: Callback that will be called when the watch is closed +- `user`: Run the operation as this user - `request_timeout`: Timeout for the request +- `timeout`: Timeout for the watch, after which the watch will be closed + +**Returns**: + +Watcher handle diff --git a/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_sync/page.mdx b/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_sync/page.mdx index adbd73f7a..9813b6714 100644 --- a/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_sync/page.mdx +++ b/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_sync/page.mdx @@ -1,270 +1,305 @@ -## Filesystem + + +## Sandbox ```python -class Filesystem() +class Sandbox(SandboxSetup, SandboxApi) ``` -Manager for interacting with the filesystem in the sandbox. +E2B cloud sandbox gives your agent a full cloud development environment that's sandboxed. +That means: +- Access to Linux OS +- Using filesystem (create, list, and delete files and dirs) +- Run commands +- Sandboxed - you can run any code +- Access to the internet -#### read +Check usage docs - https://e2b.dev/docs/sandbox/overview + +These cloud sandboxes are meant to be used for agents. Like a sandboxed playgrounds, where the agent can do whatever it wants. + +Use the `Sandbox()` to create a new sandbox. + +**Example**: ```python -def read(path: str, - format: Literal["text", "bytes", "stream"] = "text", - user: Username = "user", - request_timeout: Optional[float] = None) +sandbox = Sandbox() ``` -Reads a whole file content and returns it in requested format (text by default). -:param path: Path to the file -:param format: Format of the file content -:param user: Run the operation as this user -:param request_timeout: Timeout for the request -:return File content in requested format +#### files +```python +@property +def files() -> Filesystem +``` +Filesystem module for interacting with the sandbox's filesystem -#### write + +#### commands ```python -def write(path: str, - data: Union[str, bytes, IO], - user: Username = "user", - request_timeout: Optional[float] = None) -> EntryInfo +@property +def commands() -> Process ``` -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. +Commands module for interacting with the sandbox's processes -**Arguments**: -- `path`: Path to the file -- `data`: Data to write to the file -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request +#### pty -**Returns**: +```python +@property +def pty() -> Pty +``` -Information about the written file +PTY module for interacting with the sandbox's pseudo-terminal -#### list +#### sandbox\_id ```python -def list(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> List[EntryInfo] +@property +def sandbox_id() -> str ``` -Lists entries in a directory. +Unique identifier of the sandbox -**Arguments**: -- `path`: Path to the directory -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request +#### envd\_api\_url -**Returns**: +```python +@property +def envd_api_url() -> str +``` -List of entries in the directory +Get the sandbox API URL -#### exists +#### connection\_config ```python -def exists(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> bool +@property +def connection_config() -> ConnectionConfig ``` -Checks if a file or a directory exists. +Get the ConnectionConfig object -:param path: Path to a file or a directory -:param user Run the operation as this user -:param request_timeout Timeout for the request +#### \_\_init\_\_ +```python +def __init__(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, + sandbox_id: Optional[str] = None, + request_timeout: Optional[float] = None) +``` -#### remove +Instantiate sandbox + + +#### is\_running ```python -def remove(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> None +def is_running(request_timeout: Optional[float] = None) -> bool ``` -Removes a file or a directory. +Check if the sandbox is running. -**Arguments**: +**Returns**: -- `path`: Path to a file or a directory -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request +`True` if the sandbox is running, `False` otherwise +Example +```python +sandbox = Sandbox() +sandbox.is_running() # Returns True +sandbox.kill() +sandbox.is_running() # Returns False +``` -#### rename + +#### connect ```python -def rename(old_path: str, - new_path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> EntryInfo +@classmethod +def connect(cls, + sandbox_id: str, + api_key: Optional[str] = None, + domain: Optional[str] = None, + debug: Optional[bool] = None) ``` -Renames a file or directory from one path to another. +Connects to an existing Sandbox. -:param old_path Path to the file or directory to move -:param new_path Path to move the file or directory to -:param user Run the operation as this user -:param request_timeout Timeout for the request +**Arguments**: -:return: Information about the renamed file or directory +- `sandbox_id`: Sandbox ID +- `api_key`: E2B API Key +- `domain`: E2B Domain (use only if you self-host E2B) +- `debug`: For developing purposes, uses a local sandbox +**Returns**: +Sandbox object +@example +```python +sandbox = Sandbox() +sandbox_id = sandbox.sandbox_id -#### make\_dir +same_sandbox = Sandbox.connect(sandbox_id) + + +#### kill ```python -def make_dir(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> bool +@class_method_variant("_cls_kill") +def kill(request_timeout: Optional[float] = None) -> bool ``` -Creates a new directory and all directories along the way if needed on the specified path. +Kill the sandbox. **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 **Returns**: -True if the directory was created, False if the directory already exists +`True` if the sandbox was killed, `False` if the sandbox was not found -#### watch +#### set\_timeout ```python -def watch(path: str, - user: Username = "user", - request_timeout: Optional[float] = None, - timeout: Optional[float] = 60) -> WatchHandle +@class_method_variant("_cls_set_timeout") +def set_timeout(timeout: int, request_timeout: Optional[float] = None) -> None ``` -Watches directory for filesystem events. The watch will be closed after the timeout. +Set the sandbox's timeout, after which the sandbox will be automatically killed. -To get the events, you need to iterate over the returned WatchHandle. +The sandbox can be kept alive for a maximum of 24 hours from the time of creation. +If you try to set the timeout to a period, which exceeds the maximum limit, the timeout will be set to the maximum limit. **Arguments**: -- `path`: Path to a directory that will be watched -- `user`: Run the operation as this user +- `timeout`: Duration in milliseconds. Must be between 0 and 86400000 milliseconds (24 hours). - `request_timeout`: Timeout for the request -- `timeout`: Timeout for the watch, after which the watch will be closed - -**Returns**: - -Watcher handle -## WatchHandle +## Process ```python -class WatchHandle() +class Process() ``` -Handle for watching filesystem events. It is used to iterate over the events in the watched directory. - -#### close +#### list ```python -def close() +def list(request_timeout: Optional[float] = None) -> List[ProcessInfo] ``` -Stop watching the directory. +Lists all running processes. -**Warnings**: +**Arguments**: - You won't get any event if you don't iterate over the handle before closing it. +- `request_timeout`: Request timeout +**Returns**: +List of running processes -## ProcessHandle +#### kill ```python -class ProcessHandle() +def kill(pid: int, request_timeout: Optional[float] = None) -> bool ``` -Class representing a process. It provides methods for waiting and killing the process. -It is also used to iterate over the process output. +Kills a process. +**Arguments**: -#### pid +- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. +- `request_timeout`: Request timeout -```python -@property -def pid() -``` +**Returns**: -Get the process ID. +`True` if the process was killed, `False` if the process was not found -#### disconnect +#### send\_stdin ```python -def disconnect() -> None +def send_stdin(pid: int, data: str, request_timeout: Optional[float] = None) ``` -Disconnect from the process. It does not kill the process. It only stops receiving events from the process. +Sends data to the stdin of a process. +:param pid Process ID to send data to. You can get the list of processes using `sandbox.commands.list()`. +:param data: Data to send to the process +:param request_timeout: Request timeout -#### wait -```python -def wait(on_pty: Optional[Callable[[PtyOutput], None]] = None, - on_stdout: Optional[Callable[[str], None]] = None, - on_stderr: Optional[Callable[[str], None]] = None) -> ProcessResult -``` -Waits for the process to finish and returns the result. +#### run -If the process exits with a non-zero exit code, it throws a `ProcessExitException`. - -**Arguments**: +```python +def run(cmd: str, + background: Union[bool, None] = None, + envs: Optional[Dict[str, str]] = None, + user: Username = "user", + cwd: Optional[str] = None, + on_stdout: Optional[Callable[[str], None]] = None, + on_stderr: Optional[Callable[[str], None]] = None, + timeout: Optional[float] = 60, + request_timeout: Optional[float] = None) +``` -- `on_pty`: Callback for pty output -- `on_stdout`: Callback for stdout output -- `on_stderr`: Callback for stderr output +Starts a new process and depending on the `background` parameter, waits for the process to finish or not. -**Returns**: +:param cmd Command to execute +:param background: + If `True`, the function will return a `ProcessHandle` object that can be used to interact with the process. + If `False`, the function will wait for the process to finish and return a `ProcessResult` object. +:param envs: Environment variables +:param user: User to run the process as +:param cwd: Working directory +:param on_stdout: Callback for stdout +:param on_stderr: Callback for stderr +:param timeout: Timeout for the maximum time the process is allowed to run +:param request_timeout: Timeout for the request +:return: `ProcessHandle` if `background` is `True`, `ProcessResult` if `background` is `False` -Process result -#### kill +#### connect ```python -def kill() -> bool +def connect(pid: int, + timeout: Optional[float] = 60, + request_timeout: Optional[float] = None) ``` -Kills the process. +Connects to an existing process. -**Returns**: +**Arguments**: -Whether the process was killed successfully +- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. +- `timeout`: Timeout for the connection +- `request_timeout`: Request timeout @@ -359,303 +394,268 @@ Resizes a PTY process (changes the number of columns and rows in the terminal). -## Process +## ProcessHandle ```python -class Process() +class ProcessHandle() ``` +Class representing a process. It provides methods for waiting and killing the process. +It is also used to iterate over the process output. -#### list + +#### pid ```python -def list(request_timeout: Optional[float] = None) -> List[ProcessInfo] +@property +def pid() ``` -Lists all running processes. +Get the process ID. -**Arguments**: -- `request_timeout`: Request timeout +#### disconnect -**Returns**: +```python +def disconnect() -> None +``` -List of running processes +Disconnect from the process. It does not kill the process. It only stops receiving events from the process. -#### kill +#### wait ```python -def kill(pid: int, request_timeout: Optional[float] = None) -> bool +def wait(on_pty: Optional[Callable[[PtyOutput], None]] = None, + on_stdout: Optional[Callable[[str], None]] = None, + on_stderr: Optional[Callable[[str], None]] = None) -> ProcessResult ``` -Kills a process. +Waits for the process to finish and returns the result. + +If the process exits with a non-zero exit code, it throws a `ProcessExitException`. **Arguments**: -- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. -- `request_timeout`: Request timeout +- `on_pty`: Callback for pty output +- `on_stdout`: Callback for stdout output +- `on_stderr`: Callback for stderr output **Returns**: -`True` if the process was killed, `False` if the process was not found +Process result -#### send\_stdin +#### kill ```python -def send_stdin(pid: int, data: str, request_timeout: Optional[float] = None) +def kill() -> bool ``` -Sends data to the stdin of a process. +Kills the process. -:param pid Process ID to send data to. You can get the list of processes using `sandbox.commands.list()`. -:param data: Data to send to the process -:param request_timeout: Request timeout +**Returns**: +Whether the process was killed successfully -#### run -```python -def run(cmd: str, - background: Union[bool, None] = None, - envs: Optional[Dict[str, str]] = None, - user: Username = "user", - cwd: Optional[str] = None, - on_stdout: Optional[Callable[[str], None]] = None, - on_stderr: Optional[Callable[[str], None]] = None, - timeout: Optional[float] = 60, - request_timeout: Optional[float] = None) -``` -Starts a new process and depending on the `background` parameter, waits for the process to finish or not. +## WatchHandle -:param cmd Command to execute -:param background: - If `True`, the function will return a `ProcessHandle` object that can be used to interact with the process. - If `False`, the function will wait for the process to finish and return a `ProcessResult` object. -:param envs: Environment variables -:param user: User to run the process as -:param cwd: Working directory -:param on_stdout: Callback for stdout -:param on_stderr: Callback for stderr -:param timeout: Timeout for the maximum time the process is allowed to run -:param request_timeout: Timeout for the request -:return: `ProcessHandle` if `background` is `True`, `ProcessResult` if `background` is `False` +```python +class WatchHandle() +``` +Handle for watching filesystem events. It is used to iterate over the events in the watched directory. -#### connect +#### close ```python -def connect(pid: int, - timeout: Optional[float] = 60, - request_timeout: Optional[float] = None) +def close() ``` -Connects to an existing process. - -**Arguments**: - -- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. -- `timeout`: Timeout for the connection -- `request_timeout`: Request timeout +Stop watching the directory. +**Warnings**: + You won't get any event if you don't iterate over the handle before closing it. -## Sandbox +## Filesystem ```python -class Sandbox(SandboxSetup, SandboxApi) +class Filesystem() ``` -E2B cloud sandbox gives your agent a full cloud development environment that's sandboxed. - -That means: -- Access to Linux OS -- Using filesystem (create, list, and delete files and dirs) -- Run commands -- Sandboxed - you can run any code -- Access to the internet - -Check usage docs - https://e2b.dev/docs/sandbox/overview +Manager for interacting with the filesystem in the sandbox. -These cloud sandboxes are meant to be used for agents. Like a sandboxed playgrounds, where the agent can do whatever it wants. -Use the `Sandbox()` to create a new sandbox. - -**Example**: +#### read ```python -sandbox = Sandbox() +def read(path: str, + format: Literal["text", "bytes", "stream"] = "text", + user: Username = "user", + request_timeout: Optional[float] = None) ``` +Reads a whole file content and returns it in requested format (text by default). -#### files - -```python -@property -def files() -> Filesystem -``` +:param path: Path to the file +:param format: Format of the file content +:param user: Run the operation as this user +:param request_timeout: Timeout for the request +:return File content in requested format -Filesystem module for interacting with the sandbox's filesystem -#### commands +#### write ```python -@property -def commands() -> Process +def write(path: str, + data: Union[str, bytes, IO], + user: Username = "user", + request_timeout: Optional[float] = None) -> EntryInfo ``` -Commands module for interacting with the sandbox's processes +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, the directory will get created. -#### pty +**Arguments**: -```python -@property -def pty() -> Pty -``` +- `path`: Path to the file +- `data`: Data to write to the file +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request -PTY module for interacting with the sandbox's pseudo-terminal +**Returns**: +Information about the written file -#### sandbox\_id + +#### list ```python -@property -def sandbox_id() -> str +def list(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> List[EntryInfo] ``` -Unique identifier of the sandbox +Lists entries in a directory. +**Arguments**: -#### envd\_api\_url +- `path`: Path to the directory +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request -```python -@property -def envd_api_url() -> str -``` +**Returns**: -Get the sandbox API URL +List of entries in the directory -#### connection\_config +#### exists ```python -@property -def connection_config() -> ConnectionConfig +def exists(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> bool ``` -Get the ConnectionConfig object - - -#### \_\_init\_\_ +Checks if a file or a directory exists. -```python -def __init__(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, - sandbox_id: Optional[str] = None, - request_timeout: Optional[float] = None) -``` +:param path: Path to a file or a directory +:param user Run the operation as this user +:param request_timeout Timeout for the request -Instantiate sandbox -#### is\_running +#### remove ```python -def is_running(request_timeout: Optional[float] = None) -> bool +def remove(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> None ``` -Check if the sandbox is running. - -**Returns**: +Removes a file or a directory. -`True` if the sandbox is running, `False` otherwise -Example -```python -sandbox = Sandbox() -sandbox.is_running() # Returns True +**Arguments**: -sandbox.kill() -sandbox.is_running() # Returns False -``` +- `path`: Path to a file or a directory +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request -#### connect +#### rename ```python -@classmethod -def connect(cls, - sandbox_id: str, - api_key: Optional[str] = None, - domain: Optional[str] = None, - debug: Optional[bool] = None) +def rename(old_path: str, + new_path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> EntryInfo ``` -Connects to an existing Sandbox. - -**Arguments**: - -- `sandbox_id`: Sandbox ID -- `api_key`: E2B API Key -- `domain`: E2B Domain (use only if you self-host E2B) -- `debug`: For developing purposes, uses a local sandbox +Renames a file or directory from one path to another. -**Returns**: +:param old_path Path to the file or directory to move +:param new_path Path to move the file or directory to +:param user Run the operation as this user +:param request_timeout Timeout for the request -Sandbox object -@example -```python -sandbox = Sandbox() -sandbox_id = sandbox.sandbox_id +:return: Information about the renamed file or directory -same_sandbox = Sandbox.connect(sandbox_id) -#### kill +#### make\_dir ```python -@class_method_variant("_cls_kill") -def kill(request_timeout: Optional[float] = None) -> bool +def make_dir(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> bool ``` -Kill the sandbox. +Creates 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 **Returns**: -`True` if the sandbox was killed, `False` if the sandbox was not found +True if the directory was created, False if the directory already exists -#### set\_timeout +#### watch ```python -@class_method_variant("_cls_set_timeout") -def set_timeout(timeout: int, request_timeout: Optional[float] = None) -> None +def watch(path: str, + user: Username = "user", + request_timeout: Optional[float] = None, + timeout: Optional[float] = 60) -> WatchHandle ``` -Set the sandbox's timeout, after which the sandbox will be automatically killed. +Watches directory for filesystem events. The watch will be closed after the timeout. -The sandbox can be kept alive for a maximum of 24 hours from the time of creation. -If you try to set the timeout to a period, which exceeds the maximum limit, the timeout will be set to the maximum limit. +To get the events, you need to iterate over the returned WatchHandle. **Arguments**: -- `timeout`: Duration in milliseconds. Must be between 0 and 86400000 milliseconds (24 hours). +- `path`: Path to a directory that will be watched +- `user`: Run the operation as this user - `request_timeout`: Timeout for the request +- `timeout`: Timeout for the watch, after which the watch will be closed + +**Returns**: + +Watcher handle