From 7d93190e42c0f26bb249bc1405b2f3125092d21d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 15 Nov 2024 21:15:06 +0000 Subject: [PATCH] [skip ci] Release new versions --- .changeset/stale-eels-drive.md | 5 - .../js-sdk/v1.0.5/errors/page.mdx | 231 +++++ .../js-sdk/v1.0.5/filesystem/page.mdx | 518 ++++++++++ .../js-sdk/v1.0.5/sandbox/page.mdx | 581 +++++++++++ .../python-sdk/v1.0.3/sandbox_async/page.mdx | 962 +++++++++--------- .../python-sdk/v1.0.3/sandbox_sync/page.mdx | 906 ++++++++--------- packages/js-sdk/package.json | 2 +- 7 files changed, 2265 insertions(+), 940 deletions(-) delete mode 100644 .changeset/stale-eels-drive.md create mode 100644 apps/web/src/app/(docs)/docs/api-reference/js-sdk/v1.0.5/errors/page.mdx create mode 100644 apps/web/src/app/(docs)/docs/api-reference/js-sdk/v1.0.5/filesystem/page.mdx create mode 100644 apps/web/src/app/(docs)/docs/api-reference/js-sdk/v1.0.5/sandbox/page.mdx diff --git a/.changeset/stale-eels-drive.md b/.changeset/stale-eels-drive.md deleted file mode 100644 index 7ef26e519..000000000 --- a/.changeset/stale-eels-drive.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'e2b': patch ---- - -Update protobuf version diff --git a/apps/web/src/app/(docs)/docs/api-reference/js-sdk/v1.0.5/errors/page.mdx b/apps/web/src/app/(docs)/docs/api-reference/js-sdk/v1.0.5/errors/page.mdx new file mode 100644 index 000000000..f989f00a5 --- /dev/null +++ b/apps/web/src/app/(docs)/docs/api-reference/js-sdk/v1.0.5/errors/page.mdx @@ -0,0 +1,231 @@ +# errors + +## Classes + +### AuthenticationError + +Thrown when authentication fails. + +#### Constructors + +##### new AuthenticationError() + +> **new AuthenticationError**(`message`): `AuthenticationError` + +###### Parameters + +• **message**: `any` + +###### Returns + +`AuthenticationError` + +###### Defined in + +errors.ts:72 + +*** + +### InvalidArgumentError + +Thrown when an invalid argument is provided. + +#### Constructors + +##### new InvalidArgumentError() + +> **new InvalidArgumentError**(`message`): `InvalidArgumentError` + +###### Parameters + +• **message**: `string` + +###### Returns + +`InvalidArgumentError` + +###### Defined in + +errors.ts:42 + +*** + +### NotEnoughSpaceError + +Thrown when there is not enough disk space. + +#### Constructors + +##### new NotEnoughSpaceError() + +> **new NotEnoughSpaceError**(`message`): `NotEnoughSpaceError` + +###### Parameters + +• **message**: `string` + +###### Returns + +`NotEnoughSpaceError` + +###### Defined in + +errors.ts:52 + +*** + +### NotFoundError + +Thrown when a resource is not found. + +#### Constructors + +##### new NotFoundError() + +> **new NotFoundError**(`message`): `NotFoundError` + +###### Parameters + +• **message**: `string` + +###### Returns + +`NotFoundError` + +###### Defined in + +errors.ts:62 + +*** + +### RateLimitError + +Thrown when the API rate limit is exceeded. + +#### Constructors + +##### new RateLimitError() + +> **new RateLimitError**(`message`): `RateLimitError` + +###### Parameters + +• **message**: `any` + +###### Returns + +`RateLimitError` + +###### Defined in + +errors.ts:92 + +*** + +### SandboxError + +Base class for all sandbox errors. + +Thrown when general sandbox errors occur. + +#### Extended by + +- `TimeoutError` +- `InvalidArgumentError` +- `NotEnoughSpaceError` +- `NotFoundError` +- `AuthenticationError` +- `TemplateError` +- `RateLimitError` + +#### Constructors + +##### new SandboxError() + +> **new SandboxError**(`message`): `SandboxError` + +###### Parameters + +• **message**: `any` + +###### Returns + +`SandboxError` + +###### Defined in + +errors.ts:14 + +*** + +### TemplateError + +Thrown when the template uses old envd version. It isn't compatible with the new SDK. + +#### Constructors + +##### new TemplateError() + +> **new TemplateError**(`message`): `TemplateError` + +###### Parameters + +• **message**: `string` + +###### Returns + +`TemplateError` + +###### Defined in + +errors.ts:82 + +*** + +### TimeoutError + +Thrown when a timeout error occurs. + +The [unavailable] error type is caused by sandbox timeout. + +The [canceled] error type is caused by exceeding request timeout. + +The [deadline_exceeded] error type is caused by exceeding the timeout for command execution, watch, etc. + +The [unknown] error type is sometimes caused by the sandbox timeout when the request is not processed correctly. + +#### Constructors + +##### new TimeoutError() + +> **new TimeoutError**(`message`): `TimeoutError` + +###### Parameters + +• **message**: `string` + +###### Returns + +`TimeoutError` + +###### Defined in + +errors.ts:32 + +## Functions + +### formatSandboxTimeoutError() + +> **formatSandboxTimeoutError**(`message`): `TimeoutError` + +#### Parameters + +• **message**: `string` + +#### Returns + +`TimeoutError` + +#### Defined in + +errors.ts:2 diff --git a/apps/web/src/app/(docs)/docs/api-reference/js-sdk/v1.0.5/filesystem/page.mdx b/apps/web/src/app/(docs)/docs/api-reference/js-sdk/v1.0.5/filesystem/page.mdx new file mode 100644 index 000000000..e1a6f8be2 --- /dev/null +++ b/apps/web/src/app/(docs)/docs/api-reference/js-sdk/v1.0.5/filesystem/page.mdx @@ -0,0 +1,518 @@ +# sandbox/filesystem + +## Enumerations + +### FileType + +Sandbox filesystem object type. + +#### Enumeration Members + +##### DIR + +> **DIR**: `"dir"` + +Filesystem object is a directory. + +###### Defined in + +sandbox/filesystem/index.ts:54 + +##### FILE + +> **FILE**: `"file"` + +Filesystem object is a file. + +###### Defined in + +sandbox/filesystem/index.ts:50 + +## Classes + +### Filesystem + +Module for interacting with the sandbox filesystem. + +#### Constructors + +##### new Filesystem() + +> **new Filesystem**(`transport`, `envdApi`, `connectionConfig`): `Filesystem` + +###### Parameters + +• **transport**: `Transport` + +• **envdApi**: `EnvdApiClient` + +• **connectionConfig**: `ConnectionConfig` + +###### Returns + +`Filesystem` + +###### Defined in + +sandbox/filesystem/index.ts:103 + +#### Methods + +##### exists() + +> **exists**(`path`, `opts`?): `Promise`\<`boolean`\> + +Check if a file or a directory exists. + +###### Parameters + +• **path**: `string` + +path to a file or a directory + +• **opts?**: `FilesystemRequestOpts` + +connection options. + +###### Returns + +`Promise`\<`boolean`\> + +`true` if the file or directory exists, `false` otherwise + +###### Defined in + +sandbox/filesystem/index.ts:401 + +##### list() + +> **list**(`path`, `opts`?): `Promise`\<`EntryInfo`[]\> + +List entries in a directory. + +###### Parameters + +• **path**: `string` + +path to the directory. + +• **opts?**: `FilesystemRequestOpts` + +connection options. + +###### Returns + +`Promise`\<`EntryInfo`[]\> + +list of entries in the sandbox filesystem directory. + +###### Defined in + +sandbox/filesystem/index.ts:272 + +##### makeDir() + +> **makeDir**(`path`, `opts`?): `Promise`\<`boolean`\> + +Create a new directory and all directories along the way if needed on the specified path. + +###### Parameters + +• **path**: `string` + +path to a new directory. For example '/dirA/dirB' when creating 'dirB'. + +• **opts?**: `FilesystemRequestOpts` + +connection options. + +###### Returns + +`Promise`\<`boolean`\> + +`true` if the directory was created, `false` if it already exists. + +###### Defined in + +sandbox/filesystem/index.ts:310 + +##### read() + +###### read(path, opts) + +> **read**(`path`, `opts`?): `Promise`\<`string`\> + +Read file content as a `string`. + +You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type. + +###### Parameters + +• **path**: `string` + +path to the file. + +• **opts?**: `FilesystemRequestOpts` & `object` + +connection options. + +###### Returns + +`Promise`\<`string`\> + +file content as string + +###### Defined in + +sandbox/filesystem/index.ts:122 + +###### read(path, opts) + +> **read**(`path`, `opts`?): `Promise`\<`Uint8Array`\> + +Read file content as a `Uint8Array`. + +You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type. + +###### Parameters + +• **path**: `string` + +path to the file. + +• **opts?**: `FilesystemRequestOpts` & `object` + +connection options. + +###### Returns + +`Promise`\<`Uint8Array`\> + +file content as `Uint8Array` + +###### Defined in + +sandbox/filesystem/index.ts:137 + +###### read(path, opts) + +> **read**(`path`, `opts`?): `Promise`\<`Blob`\> + +Read file content as a `Blob`. + +You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type. + +###### Parameters + +• **path**: `string` + +path to the file. + +• **opts?**: `FilesystemRequestOpts` & `object` + +connection options. + +###### Returns + +`Promise`\<`Blob`\> + +file content as `Blob` + +###### Defined in + +sandbox/filesystem/index.ts:152 + +###### read(path, opts) + +> **read**(`path`, `opts`?): `Promise`\<`ReadableStream`\<`Uint8Array`\>\> + +Read file content as a `ReadableStream`. + +You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type. + +###### Parameters + +• **path**: `string` + +path to the file. + +• **opts?**: `FilesystemRequestOpts` & `object` + +connection options. + +###### Returns + +`Promise`\<`ReadableStream`\<`Uint8Array`\>\> + +file content as `ReadableStream` + +###### Defined in + +sandbox/filesystem/index.ts:167 + +##### remove() + +> **remove**(`path`, `opts`?): `Promise`\<`void`\> + +Remove a file or directory. + +###### Parameters + +• **path**: `string` + +path to a file or directory. + +• **opts?**: `FilesystemRequestOpts` + +connection options. + +###### Returns + +`Promise`\<`void`\> + +###### Defined in + +sandbox/filesystem/index.ts:379 + +##### rename() + +> **rename**(`oldPath`, `newPath`, `opts`?): `Promise`\<`EntryInfo`\> + +Rename a file or directory. + +###### Parameters + +• **oldPath**: `string` + +path to the file or directory to rename. + +• **newPath**: `string` + +new path for the file or directory. + +• **opts?**: `FilesystemRequestOpts` + +connection options. + +###### Returns + +`Promise`\<`EntryInfo`\> + +information about renamed file or directory. + +###### Defined in + +sandbox/filesystem/index.ts:341 + +##### watchDir() + +> **watchDir**(`path`, `onEvent`, `opts`?): `Promise`\<`WatchHandle`\> + +Start watching a directory for filesystem events. + +###### Parameters + +• **path**: `string` + +path to directory to watch. + +• **onEvent** + +callback to call when an event in the directory occurs. + +• **opts?**: `WatchOpts` + +connection options. + +###### Returns + +`Promise`\<`WatchHandle`\> + +`WatchHandle` object for stopping watching directory. + +###### Defined in + +sandbox/filesystem/index.ts:432 + +##### write() + +> **write**(`path`, `data`, `opts`?): `Promise`\<`EntryInfo`\> + +Write content to a file. + +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. + +###### Parameters + +• **path**: `string` + +path to file. + +• **data**: `string` \| `ArrayBuffer` \| `Blob` \| `ReadableStream`\<`any`\> + +data to write to the file. Data can be a string, `ArrayBuffer`, `Blob`, or `ReadableStream`. + +• **opts?**: `FilesystemRequestOpts` + +connection options. + +###### Returns + +`Promise`\<`EntryInfo`\> + +information about the written file + +###### Defined in + +sandbox/filesystem/index.ts:223 + +## Interfaces + +### EntryInfo + +Sandbox filesystem object information. + +#### Properties + +##### name + +> **name**: `string` + +Name of the filesystem object. + +###### Defined in + +sandbox/filesystem/index.ts:32 + +##### path + +> **path**: `string` + +Path to the filesystem object. + +###### Defined in + +sandbox/filesystem/index.ts:40 + +##### type? + +> `optional` **type**: `FileType` + +Type of the filesystem object. + +###### Defined in + +sandbox/filesystem/index.ts:36 + +*** + +### FilesystemRequestOpts + +Options for the sandbox filesystem operations. + +#### Extended by + +- `WatchOpts` + +#### Properties + +##### requestTimeoutMs? + +> `optional` **requestTimeoutMs**: `number` + +Timeout for requests to the API in **milliseconds**. + +###### Default + +```ts +30_000 // 30 seconds +``` + +###### Defined in + +connectionConfig.ts:42 + +##### user? + +> `optional` **user**: `Username` + +User to use for the operation in the sandbox. +This affects the resolution of relative paths and ownership of the created filesystem objects. + +###### Defined in + +sandbox/filesystem/index.ts:75 + +*** + +### WatchOpts + +Options for watching a directory. + +#### Properties + +##### onExit()? + +> `optional` **onExit**: (`err`?) => `void` \| `Promise`\<`void`\> + +Callback to call when the watch operation stops. + +###### Parameters + +• **err?**: `Error` + +###### Returns + +`void` \| `Promise`\<`void`\> + +###### Defined in + +sandbox/filesystem/index.ts:92 + +##### requestTimeoutMs? + +> `optional` **requestTimeoutMs**: `number` + +Timeout for requests to the API in **milliseconds**. + +###### Default + +```ts +30_000 // 30 seconds +``` + +###### Defined in + +connectionConfig.ts:42 + +##### timeoutMs? + +> `optional` **timeoutMs**: `number` + +Timeout for the watch operation in **milliseconds**. +You can pass `0` to disable the timeout. + +###### Default + +```ts +60_000 // 60 seconds +``` + +###### Defined in + +sandbox/filesystem/index.ts:88 + +##### user? + +> `optional` **user**: `Username` + +User to use for the operation in the sandbox. +This affects the resolution of relative paths and ownership of the created filesystem objects. + +###### Defined in + +sandbox/filesystem/index.ts:75 diff --git a/apps/web/src/app/(docs)/docs/api-reference/js-sdk/v1.0.5/sandbox/page.mdx b/apps/web/src/app/(docs)/docs/api-reference/js-sdk/v1.0.5/sandbox/page.mdx new file mode 100644 index 000000000..6c4cae338 --- /dev/null +++ b/apps/web/src/app/(docs)/docs/api-reference/js-sdk/v1.0.5/sandbox/page.mdx @@ -0,0 +1,581 @@ +# sandbox + +## Classes + +### Sandbox + +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 Sandbox.create to create a new sandbox. + +#### Example + +```ts +import { Sandbox } from 'e2b' + +const sandbox = await Sandbox.create() +``` + +#### Properties + +##### commands + +> `readonly` **commands**: `Commands` + +Module for running commands in the sandbox + +###### Defined in + +sandbox/index.ts:74 + +##### files + +> `readonly` **files**: `Filesystem` + +Module for interacting with the sandbox filesystem + +###### Defined in + +sandbox/index.ts:70 + +##### pty + +> `readonly` **pty**: `Pty` + +Module for interacting with the sandbox pseudo-terminals + +###### Defined in + +sandbox/index.ts:78 + +##### sandboxId + +> `readonly` **sandboxId**: `string` + +Unique identifier of the sandbox. + +###### Defined in + +sandbox/index.ts:83 + +#### Methods + +##### downloadUrl() + +> **downloadUrl**(`path`): `string` + +Get the URL to download a file from the sandbox. + +###### Parameters + +• **path**: `string` + +path to the file to download. + +###### Returns + +`string` + +URL for downloading file. + +###### Defined in + +sandbox/index.ts:339 + +##### getHost() + +> **getHost**(`port`): `string` + +Get the host address for the specified sandbox port. +You can then use this address to connect to the sandbox port from outside the sandbox via HTTP or WebSocket. + +###### Parameters + +• **port**: `number` + +number of the port in the sandbox. + +###### Returns + +`string` + +host address of the sandbox port. + +###### Example + +```ts +const sandbox = await Sandbox.create() +// Start an HTTP server +await sandbox.commands.exec('python3 -m http.server 3000') +// Get the hostname of the HTTP server +const serverURL = sandbox.getHost(3000) +`` + +###### Defined in + +sandbox/index.ts:237 + +##### isRunning() + +> **isRunning**(`opts`?): `Promise`\<`boolean`\> + +Check if the sandbox is running. + +###### Parameters + +• **opts?**: `Pick`\<`ConnectionOpts`, `"requestTimeoutMs"`\> + +###### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox is running, `false` otherwise. + +###### Example + +```ts +const sandbox = await Sandbox.create() +await sandbox.isRunning() // Returns true + +await sandbox.kill() +await sandbox.isRunning() // Returns false +``` + +###### Defined in + +sandbox/index.ts:259 + +##### kill() + +> **kill**(`opts`?): `Promise`\<`void`\> + +Kill the sandbox. + +###### Parameters + +• **opts?**: `Pick`\<`SandboxOpts`, `"requestTimeoutMs"`\> + +connection options. + +###### Returns + +`Promise`\<`void`\> + +###### Defined in + +sandbox/index.ts:310 + +##### setTimeout() + +> **setTimeout**(`timeoutMs`, `opts`?): `Promise`\<`void`\> + +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 `.setTimeout`. +Maximum time a sandbox can be kept alive is 24 hours (86_400_000 milliseconds) for Pro users and 1 hour (3_600_000 milliseconds) for Hobby users. + +###### Parameters + +• **timeoutMs**: `number` + +timeout in **milliseconds**. + +• **opts?**: `Pick`\<`SandboxOpts`, `"requestTimeoutMs"`\> + +connection options. + +###### Returns + +`Promise`\<`void`\> + +###### Defined in + +sandbox/index.ts:290 + +##### uploadUrl() + +> **uploadUrl**(`path`?): `string` + +Get the URL to upload a file to the sandbox. + +You have to send a POST request to this URL with the file as multipart/form-data. + +###### Parameters + +• **path?**: `string` + +the directory where to upload the file, defaults to user's home directory. + +###### Returns + +`string` + +URL for uploading file. + +###### Defined in + +sandbox/index.ts:328 + +##### connect() + +> `static` **connect**\<`S`\>(`this`, `sandboxId`, `opts`?): `Promise`\<`InstanceType`\<`S`\>\> + +Connect to an existing sandbox. +With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). + +###### Type Parameters + +• **S** *extends* *typeof* `Sandbox` + +###### Parameters + +• **this**: `S` + +• **sandboxId**: `string` + +sandbox ID. + +• **opts?**: `Omit`\<`SandboxOpts`, `"timeoutMs"` \| `"metadata"` \| `"envs"`\> + +connection options. + +###### Returns + +`Promise`\<`InstanceType`\<`S`\>\> + +sandbox instance for the existing sandbox. + +###### Example + +```ts +const sandbox = await Sandbox.create() +const sandboxId = sandbox.sandboxId + +// Connect to the same sandbox. +const sameSandbox = await Sandbox.connect(sandboxId) +``` + +###### Defined in + +sandbox/index.ts:209 + +##### create() + +###### create(this, opts) + +> `static` **create**\<`S`\>(`this`, `opts`?): `Promise`\<`InstanceType`\<`S`\>\> + +Create a new sandbox from the default `base` sandbox template. + +###### Type Parameters + +• **S** *extends* *typeof* `Sandbox` + +###### Parameters + +• **this**: `S` + +• **opts?**: `SandboxOpts` + +connection options. + +###### Returns + +`Promise`\<`InstanceType`\<`S`\>\> + +sandbox instance for the new sandbox. + +###### Example + +```ts +const sandbox = await Sandbox.create() +``` + +###### Constructs + +Sandbox + +###### Defined in + +sandbox/index.ts:143 + +###### create(this, template, opts) + +> `static` **create**\<`S`\>(`this`, `template`, `opts`?): `Promise`\<`InstanceType`\<`S`\>\> + +Create a new sandbox from the specified sandbox template. + +###### Type Parameters + +• **S** *extends* *typeof* `Sandbox` + +###### Parameters + +• **this**: `S` + +• **template**: `string` + +sandbox template name or ID. + +• **opts?**: `SandboxOpts` + +connection options. + +###### Returns + +`Promise`\<`InstanceType`\<`S`\>\> + +sandbox instance for the new sandbox. + +###### Example + +```ts +const sandbox = await Sandbox.create('') +``` + +###### Constructs + +Sandbox + +###### Defined in + +sandbox/index.ts:162 + +##### kill() + +> `static` **kill**(`sandboxId`, `opts`?): `Promise`\<`boolean`\> + +Kill the sandbox specified by sandbox ID. + +###### Parameters + +• **sandboxId**: `string` + +sandbox ID. + +• **opts?**: `SandboxApiOpts` + +connection options. + +###### Returns + +`Promise`\<`boolean`\> + +`true` if the sandbox was found and killed, `false` otherwise. + +###### Defined in + +sandbox/sandboxApi.ts:55 + +##### list() + +> `static` **list**(`opts`?): `Promise`\<`SandboxInfo`[]\> + +List all running sandboxes. + +###### Parameters + +• **opts?**: `SandboxApiOpts` + +connection options. + +###### Returns + +`Promise`\<`SandboxInfo`[]\> + +list of running sandboxes. + +###### Defined in + +sandbox/sandboxApi.ts:90 + +##### setTimeout() + +> `static` **setTimeout**(`sandboxId`, `timeoutMs`, `opts`?): `Promise`\<`void`\> + +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 Sandbox.setTimeout. + +Maximum time a sandbox can be kept alive is 24 hours (86_400_000 milliseconds) for Pro users and 1 hour (3_600_000 milliseconds) for Hobby users. + +###### Parameters + +• **sandboxId**: `string` + +sandbox ID. + +• **timeoutMs**: `number` + +timeout in **milliseconds**. + +• **opts?**: `SandboxApiOpts` + +connection options. + +###### Returns + +`Promise`\<`void`\> + +###### Defined in + +sandbox/sandboxApi.ts:129 + +## Interfaces + +### SandboxOpts + +Options for creating a new Sandbox. + +#### Properties + +##### accessToken? + +> `optional` **accessToken**: `string` + +E2B access token to use for authentication. + +###### Default + +```ts +E2B_ACCESS_TOKEN // environment variable +``` + +###### Defined in + +connectionConfig.ts:24 + +##### apiKey? + +> `optional` **apiKey**: `string` + +E2B API key to use for authentication. + +###### Default + +```ts +E2B_API_KEY // environment variable +``` + +###### Defined in + +connectionConfig.ts:18 + +##### debug? + +> `optional` **debug**: `boolean` + +**`Internal`** + +If true the SDK starts in the debug mode and connects to the local envd API server. + +###### Default + +E2B_DEBUG // environment variable or `false` + +###### Defined in + +connectionConfig.ts:36 + +##### domain? + +> `optional` **domain**: `string` + +Domain to use for the API. + +###### Default + +E2B_DOMAIN // environment variable or `e2b.dev` + +###### Defined in + +connectionConfig.ts:30 + +##### envs? + +> `optional` **envs**: `Record`\<`string`, `string`\> + +Custom environment variables for the sandbox. + +Used when executing commands and code in the sandbox. +Can be overridden with the `envs` argument when executing commands or code. + +###### Default + +```ts +{} +``` + +###### Defined in + +sandbox/index.ts:32 + +##### logger? + +> `optional` **logger**: `Logger` + +Logger to use for logging messages. It can accept any object that implements `Logger` interface—for example, console. + +###### Defined in + +connectionConfig.ts:46 + +##### metadata? + +> `optional` **metadata**: `Record`\<`string`, `string`\> + +Custom metadata for the sandbox. + +###### Default + +```ts +{} +``` + +###### Defined in + +sandbox/index.ts:23 + +##### requestTimeoutMs? + +> `optional` **requestTimeoutMs**: `number` + +Timeout for requests to the API in **milliseconds**. + +###### Default + +```ts +30_000 // 30 seconds +``` + +###### Defined in + +connectionConfig.ts:42 + +##### timeoutMs? + +> `optional` **timeoutMs**: `number` + +Timeout for the sandbox in **milliseconds**. +Maximum time a sandbox can be kept alive is 24 hours (86_400_000 milliseconds) for Pro users and 1 hour (3_600_000 milliseconds) for Hobby users. + +###### Default + +```ts +300_000 // 5 minutes +``` + +###### Defined in + +sandbox/index.ts:39 diff --git a/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v1.0.3/sandbox_async/page.mdx b/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v1.0.3/sandbox_async/page.mdx index 2583bcc1d..57bbc0ea5 100644 --- a/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v1.0.3/sandbox_async/page.mdx +++ b/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v1.0.3/sandbox_async/page.mdx @@ -1,489 +1,549 @@ -## Commands + + +## AsyncSandbox ```python -class Commands() +class AsyncSandbox(SandboxSetup, SandboxApi) ``` -Module for executing commands in the sandbox. +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 -#### list +Check docs [here](https://e2b.dev/docs). + +Use the `AsyncSandbox.create()` to create a new sandbox. + +**Example**: ```python -async def list(request_timeout: Optional[float] = None) -> List[ProcessInfo] -``` +from e2b import AsyncSandbox -Lists all running commands and PTY sessions. +sandbox = await AsyncSandbox.create() +``` -**Arguments**: -- `request_timeout`: Timeout for the request in **seconds** +#### files -**Returns**: +```python +@property +def files() -> Filesystem +``` -List of running commands and PTY sessions +Module for interacting with the sandbox filesystem. -#### kill +#### commands ```python -async def kill(pid: int, request_timeout: Optional[float] = None) -> bool +@property +def commands() -> Commands ``` -Kill a running command specified by its process ID. - -It uses `SIGKILL` signal to kill the command. +Module for running commands in the sandbox. -**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** +#### pty -**Returns**: +```python +@property +def pty() -> Pty +``` -`True` if the command was killed, `False` if the command was not found +Module for interacting with the sandbox pseudo-terminal. -#### send\_stdin +#### sandbox\_id ```python -async def send_stdin(pid: int, - data: str, - request_timeout: Optional[float] = None) -> None +@property +def sandbox_id() -> str ``` -Send data to command stdin. +Unique identifier of the sandbox. -: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** +#### \_\_init\_\_ + +```python +def __init__(**opts: Unpack[AsyncSandboxOpts]) +``` + +Use `AsyncSandbox.create()` to create a new sandbox instead. -#### run +#### is\_running ```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 +async def is_running(request_timeout: Optional[float] = None) -> bool ``` -Start a new command and wait until it finishes executing. +Check if the sandbox is running. **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 +`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 +``` -#### run +#### create ```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 +@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) ``` -Start a new command and return a handle to interact with it. +Create a new sandbox. + +By default, the sandbox is created from the default `base` sandbox template. **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 +- `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** **Returns**: -`AsyncCommandHandle` handle to interact with the running command +sandbox instance for the new sandbox +Use this method instead of using the constructor to create a new sandbox. #### 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 +@classmethod +async def connect(cls, + sandbox_id: str, + api_key: Optional[str] = None, + domain: Optional[str] = None, + debug: Optional[bool] = None) ``` -Connects to a running command. +Connect to an existing sandbox. -You can use `AsyncCommandHandle.wait()` to wait for the command to finish and get execution results. +With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). **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 +- `sandbox_id`: Sandbox ID +- `api_key`: E2B API Key to use for authentication, defaults to `E2B_API_KEY` environment variable **Returns**: -`AsyncCommandHandle` handle to interact with the running command - +sandbox instance for the existing sandbox +@example +```python +sandbox = await AsyncSandbox.create() +sandbox_id = sandbox.sandbox_id +same_sandbox = await AsyncSandbox.connect(sandbox_id) -## AsyncCommandHandle +#### kill ```python -class AsyncCommandHandle() +@overload +async def kill(request_timeout: Optional[float] = None) -> bool ``` -Command execution handle. +Kill the sandbox. -It provides methods for waiting for the command to finish, retrieving stdout/stderr, and killing the command. +**Arguments**: +- `request_timeout`: Timeout for the request in **seconds** + +**Returns**: + +`True` if the sandbox was killed, `False` if the sandbox was not found -#### pid + +#### kill ```python -@property -def pid() +@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) -> bool ``` -Command process ID. +Kill the sandbox specified by sandbox ID. +**Arguments**: -#### stdout +- `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** -```python -@property -def stdout() -``` +**Returns**: -Command stdout output. +`True` if the sandbox was killed, `False` if the sandbox was not found -#### stderr +#### set\_timeout ```python -@property -def stderr() +@overload +async def set_timeout(timeout: int, + request_timeout: Optional[float] = None) -> None ``` -Command stderr output. +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`. -#### error +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. -```python -@property -def error() -``` +**Arguments**: -Command execution error message. +- `timeout`: Timeout for the sandbox in **seconds** +- `request_timeout`: Timeout for the request in **seconds** -#### exit\_code +#### set\_timeout ```python -@property -def exit_code() +@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) -> None ``` -Command execution exit code. +Set the timeout of the specified sandbox. -`0` if the command finished successfully. +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`. -It is `None` if the command is still running. +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** -#### disconnect + + + +## Filesystem ```python -async def disconnect() -> None +class Filesystem() ``` -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. +Module for interacting with the filesystem in the sandbox. -#### wait +#### read ```python -async def wait() -> CommandResult +@overload +async def read(path: str, + format: Literal["text"] = "text", + user: Username = "user", + request_timeout: Optional[float] = None) -> str ``` -Wait for the command to finish and return the result. +Read file content as a `str`. -If the command exits with a non-zero exit code, it throws a `CommandExitException`. +**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**: -`CommandResult` result of command execution +File content as a `str` -#### kill +#### read ```python -async def kill() -> bool +@overload +async def read(path: str, + format: Literal["bytes"], + user: Username = "user", + request_timeout: Optional[float] = None) -> bytearray ``` -Kills the command. - -It uses `SIGKILL` signal to kill the command +Read file content as a `bytearray`. -**Returns**: +**Arguments**: -`True` if the command was killed successfully, `False` if the command was not found +- `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` -## Pty +#### read ```python -class Pty() +@overload +async def read( + path: str, + format: Literal["stream"], + user: Username = "user", + request_timeout: Optional[float] = None) -> AsyncIterator[bytes] ``` -Module for interacting with PTYs (pseudo-terminals) in the sandbox. +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** -#### kill +**Returns**: + +File content as an `AsyncIterator[bytes]` + + +#### write ```python -async def kill(pid: int, request_timeout: Optional[float] = None) -> bool +async def write(path: str, + data: Union[str, bytes, IO], + user: Username = "user", + request_timeout: Optional[float] = None) -> EntryInfo ``` -Kill PTY. +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**: -- `pid`: Process ID of the PTY +- `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**: -`true` if the PTY was killed, `false` if the PTY was not found +Information about the written file -#### send\_stdin +#### list ```python -async def send_stdin(pid: int, - data: bytes, - request_timeout: Optional[float] = None) -> None +async def list(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> List[EntryInfo] ``` -Send input to a PTY. +List entries in a directory. **Arguments**: -- `pid`: Process ID of the PTY -- `data`: Input data to send +- `path`: Path to the directory +- `user`: Run the operation as this user - `request_timeout`: Timeout for the request in **seconds** +**Returns**: + +List of entries in the directory -#### create + +#### exists ```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 +async def exists(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> bool ``` -Start a new PTY (pseudo-terminal). +Check if a file or a directory exists. **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** +- `path`: Path to a file or a directory +- `user`: Run the operation as this user - `request_timeout`: Timeout for the request in **seconds** **Returns**: -Handle to interact with the PTY +`True` if the file or directory exists, `False` otherwise -#### resize +#### remove ```python -async def resize(pid: int, - size: PtySize, - request_timeout: Optional[float] = None) +async def remove(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> None ``` -Resize PTY. - -Call this when the terminal window is resized and the number of columns and rows has changed. +Remove a file or a directory. **Arguments**: -- `pid`: Process ID of the PTY -- `size`: New size of the PTY +- `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** -## SandboxApi +**Returns**: -```python -class SandboxApi(SandboxApiBase) -``` +Information about the renamed file or directory -#### list +#### make\_dir -```python -@classmethod -async def list(cls, - api_key: Optional[str] = None, - domain: Optional[str] = None, - debug: Optional[bool] = None, - request_timeout: Optional[float] = None) -> List[SandboxInfo] +```python +async def make_dir(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> bool ``` -List all running sandboxes. +Create a new directory and all directories along the way if needed on the specified path. **Arguments**: -- `api_key`: API key to use for authentication, defaults to `E2B_API_KEY` environment variable +- `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**: -List of running sandboxes - - +`True` if the directory was created, `False` if the directory already exists -## AsyncSandbox +#### watch\_dir ```python -class AsyncSandbox(SandboxSetup, SandboxApi) +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) -> AsyncWatchHandle ``` -E2B cloud sandbox is a secure and isolated cloud environment. +Watch directory for filesystem events. -The sandbox allows you to: -- Access Linux OS -- Create, list, and delete files and directories -- Run commands -- Run isolated code -- Access the internet +**Arguments**: -Check docs [here](https://e2b.dev/docs). +- `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 -Use the `AsyncSandbox.create()` to create a new sandbox. +**Returns**: -**Example**: +`AsyncWatchHandle` object for stopping watching directory -```python -from e2b import AsyncSandbox -sandbox = await AsyncSandbox.create() -``` -#### files +## AsyncWatchHandle ```python -@property -def files() -> Filesystem +class AsyncWatchHandle() ``` -Module for interacting with the sandbox filesystem. - - -#### commands - -```python -@property -def commands() -> Commands -``` +Handle for watching a directory in the sandbox filesystem. -Module for running commands in the sandbox. +Use `.stop()` to stop watching the directory. -#### pty +#### stop ```python -@property -def pty() -> Pty +async def stop() ``` -Module for interacting with the sandbox pseudo-terminal. - - -#### sandbox\_id +Stop watching the directory. -```python -@property -def sandbox_id() -> str -``` -Unique identifier of the sandbox. -#### \_\_init\_\_ +## Commands ```python -def __init__(**opts: Unpack[AsyncSandboxOpts]) +class Commands() ``` -Use `AsyncSandbox.create()` to create a new sandbox instead. +Module for executing commands in the sandbox. -#### is\_running +#### list ```python -async def is_running(request_timeout: Optional[float] = None) -> bool +async def list(request_timeout: Optional[float] = None) -> List[ProcessInfo] ``` -Check if the sandbox is running. +Lists all running commands and PTY sessions. **Arguments**: @@ -491,434 +551,374 @@ Check if the sandbox is running. **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 -``` +List of running commands and PTY sessions -#### create +#### kill ```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 kill(pid: int, request_timeout: Optional[float] = None) -> bool ``` -Create a new sandbox. +Kill a running command specified by its process ID. -By default, the sandbox is created from the default `base` sandbox template. +It uses `SIGKILL` signal to kill the command. **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 +- `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**: -sandbox instance for the new sandbox -Use this method instead of using the constructor to create a new sandbox. +`True` if the command was killed, `False` if the command was not found -#### connect +#### send\_stdin ```python -@classmethod -async def connect(cls, - sandbox_id: str, - api_key: Optional[str] = None, - domain: Optional[str] = None, - debug: Optional[bool] = None) +async def send_stdin(pid: int, + data: str, + request_timeout: Optional[float] = None) -> 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 - -**Returns**: +Send data to command stdin. -sandbox instance for the existing sandbox -@example -```python -sandbox = await AsyncSandbox.create() -sandbox_id = sandbox.sandbox_id +: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** -same_sandbox = await AsyncSandbox.connect(sandbox_id) -#### kill +#### run ```python @overload -async def kill(request_timeout: Optional[float] = None) -> bool +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 ``` -Kill the sandbox. +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**: -`True` if the sandbox was killed, `False` if the sandbox was not found +`CommandResult` result of the command execution -#### kill +#### run ```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) -> bool +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 ``` -Kill the sandbox specified by sandbox ID. +Start a new command and return a handle to interact with it. **Arguments**: -- `sandbox_id`: Sandbox ID -- `api_key`: E2B API Key to use for authentication, defaults to `E2B_API_KEY` environment variable +- `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**: -`True` if the sandbox was killed, `False` if the sandbox was not found +`AsyncCommandHandle` handle to interact with the running command -#### set\_timeout +#### connect ```python -@overload -async def set_timeout(timeout: int, - request_timeout: Optional[float] = None) -> None +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 ``` -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`. +Connects to a running command. -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. +You can use `AsyncCommandHandle.wait()` to wait for the command to finish and get execution results. **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) -> 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. +- `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 -**Arguments**: +**Returns**: -- `sandbox_id`: Sandbox ID -- `timeout`: Timeout for the sandbox in **seconds** -- `request_timeout`: Timeout for the request in **seconds** +`AsyncCommandHandle` handle to interact with the running command -## Filesystem +## Pty ```python -class Filesystem() +class Pty() ``` -Module for interacting with the filesystem in the sandbox. +Module for interacting with PTYs (pseudo-terminals) in the sandbox. -#### read +#### kill ```python -@overload -async def read(path: str, - format: Literal["text"] = "text", - user: Username = "user", - request_timeout: Optional[float] = None) -> str +async def kill(pid: int, request_timeout: Optional[float] = None) -> bool ``` -Read file content as a `str`. +Kill PTY. **Arguments**: -- `path`: Path to the file -- `user`: Run the operation as this user -- `format`: Format of the file content—`text` by default +- `pid`: Process ID of the PTY - `request_timeout`: Timeout for the request in **seconds** **Returns**: -File content as a `str` +`true` if the PTY was killed, `false` if the PTY was not found -#### read +#### send\_stdin ```python -@overload -async def read(path: str, - format: Literal["bytes"], - user: Username = "user", - request_timeout: Optional[float] = None) -> bytearray +async def send_stdin(pid: int, + data: bytes, + request_timeout: Optional[float] = None) -> None ``` -Read file content as a `bytearray`. +Send input to a PTY. **Arguments**: -- `path`: Path to the file -- `user`: Run the operation as this user -- `format`: Format of the file content—`bytes` +- `pid`: Process ID of the PTY +- `data`: Input data to send - `request_timeout`: Timeout for the request in **seconds** -**Returns**: - -File content as a `bytearray` - -#### read +#### create ```python -@overload -async def read( - path: str, - format: Literal["stream"], +async def create( + size: PtySize, + on_data: OutputHandler[PtyOutput], user: Username = "user", - request_timeout: Optional[float] = None) -> AsyncIterator[bytes] + cwd: Optional[str] = None, + envs: Optional[Dict[str, str]] = None, + timeout: Optional[float] = 60, + request_timeout: Optional[float] = None) -> AsyncCommandHandle ``` -Read file content as a `AsyncIterator[bytes]`. +Start a new PTY (pseudo-terminal). **Arguments**: -- `path`: Path to the file -- `user`: Run the operation as this user -- `format`: Format of the file content—`stream` +- `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**: -File content as an `AsyncIterator[bytes]` +Handle to interact with the PTY -#### write +#### resize ```python -async def write(path: str, - data: Union[str, bytes, IO], - user: Username = "user", - request_timeout: Optional[float] = None) -> EntryInfo +async def resize(pid: int, + size: PtySize, + request_timeout: Optional[float] = None) ``` -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. +Resize PTY. -Writing to a file at path that doesn't exist creates the necessary directories. +Call this when the terminal window is resized and the number of columns and rows has changed. **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 +- `pid`: Process ID of the PTY +- `size`: New size of the PTY - `request_timeout`: Timeout for the request in **seconds** -**Returns**: -Information about the written file -#### list +## AsyncCommandHandle ```python -async def list(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> List[EntryInfo] +class AsyncCommandHandle() ``` -List entries in a directory. +Command execution handle. -**Arguments**: +It provides methods for waiting for the command to finish, retrieving stdout/stderr, and killing the command. -- `path`: Path to the directory -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request in **seconds** -**Returns**: +#### pid -List of entries in the directory +```python +@property +def pid() +``` + +Command process ID. -#### exists +#### stdout ```python -async def exists(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> bool +@property +def stdout() ``` -Check if a file or a directory exists. +Command stdout output. -**Arguments**: -- `path`: Path to a file or a directory -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request in **seconds** +#### stderr -**Returns**: +```python +@property +def stderr() +``` -`True` if the file or directory exists, `False` otherwise +Command stderr output. -#### remove +#### error ```python -async def remove(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> None +@property +def error() ``` -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** +Command execution error message. -#### rename +#### exit\_code ```python -async def rename(old_path: str, - new_path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> EntryInfo +@property +def exit_code() ``` -Rename a file or directory. +Command execution exit code. -**Arguments**: +`0` if the command finished successfully. -- `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** +It is `None` if the command is still running. -**Returns**: -Information about the renamed file or directory +#### disconnect + +```python +async def disconnect() -> None +``` +Disconnects from the command. -#### make\_dir +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 make_dir(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> bool +async def wait() -> CommandResult ``` -Create a new directory and all directories along the way if needed on the specified path. - -**Arguments**: +Wait for the command to finish and return the result. -- `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** +If the command exits with a non-zero exit code, it throws a `CommandExitException`. **Returns**: -`True` if the directory was created, `False` if the directory already exists +`CommandResult` result of command execution -#### watch\_dir +#### kill ```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) -> AsyncWatchHandle +async def kill() -> bool ``` -Watch directory for filesystem events. - -**Arguments**: +Kills the command. -- `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 +It uses `SIGKILL` signal to kill the command **Returns**: -`AsyncWatchHandle` object for stopping watching directory +`True` if the command was killed successfully, `False` if the command was not found -## AsyncWatchHandle +## SandboxApi ```python -class AsyncWatchHandle() +class SandboxApi(SandboxApiBase) ``` -Handle for watching a directory in the sandbox filesystem. - -Use `.stop()` to stop watching the directory. - -#### stop +#### list ```python -async def stop() +@classmethod +async def list(cls, + api_key: Optional[str] = None, + domain: Optional[str] = None, + debug: Optional[bool] = None, + request_timeout: Optional[float] = None) -> List[SandboxInfo] ``` -Stop watching the directory. +List all running sandboxes. + +**Arguments**: + +- `api_key`: API key to use for authentication, defaults to `E2B_API_KEY` environment variable +- `request_timeout`: Timeout for the request in **seconds** + +**Returns**: + +List of running sandboxes diff --git a/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v1.0.3/sandbox_sync/page.mdx b/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v1.0.3/sandbox_sync/page.mdx index 1e39bf353..ee88ace74 100644 --- a/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v1.0.3/sandbox_sync/page.mdx +++ b/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v1.0.3/sandbox_sync/page.mdx @@ -1,901 +1,901 @@ -## Commands +## Sandbox ```python -class Commands() +class Sandbox(SandboxSetup, SandboxApi) ``` -Module for executing commands in the sandbox. +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 -#### list +Check docs [here](https://e2b.dev/docs). + +Use the `Sandbox()` to create a new sandbox. + +**Example**: ```python -def list(request_timeout: Optional[float] = None) -> List[ProcessInfo] -``` +from e2b import Sandbox -Lists all running commands and PTY sessions. +sandbox = Sandbox() +``` -**Arguments**: -- `request_timeout`: Timeout for the request in **seconds** +#### files -**Returns**: +```python +@property +def files() -> Filesystem +``` -List of running commands and PTY sessions +Module for interacting with the sandbox filesystem. -#### kill +#### commands ```python -def kill(pid: int, request_timeout: Optional[float] = None) -> bool +@property +def commands() -> Commands ``` -Kills a running command specified by its process ID. - -It uses `SIGKILL` signal to kill the command. +Module for running commands in the sandbox. -**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** +#### pty -**Returns**: +```python +@property +def pty() -> Pty +``` -`True` if the command was killed, `False` if the command was not found +Module for interacting with the sandbox pseudo-terminal. -#### send\_stdin +#### sandbox\_id ```python -def send_stdin(pid: int, data: str, request_timeout: Optional[float] = None) +@property +def sandbox_id() -> str ``` -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** - +Unique identifier of the sandbox -#### run +#### \_\_init\_\_ ```python -@overload -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[Callable[[str], None]] = None, - on_stderr: Optional[Callable[[str], None]] = None, - timeout: Optional[float] = 60, - request_timeout: Optional[float] = None) -> CommandResult +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) ``` -Start a new command and wait until it finishes executing. +Create a new sandbox. + +By default, the sandbox is created from the default `base` sandbox template. **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 +- `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** **Returns**: -`CommandResult` result of the command execution +sandbox instance for the new sandbox -#### run +#### is\_running ```python -@overload -def run(cmd: str, - background: Literal[True], - envs: Optional[Dict[str, str]] = None, - user: Username = "user", - cwd: Optional[str] = None, - on_stdout: None = None, - on_stderr: None = None, - timeout: Optional[float] = 60, - request_timeout: Optional[float] = None) -> CommandHandle +def is_running(request_timeout: Optional[float] = None) -> bool ``` -Start a new command and return a handle to interact with it. +Check if the sandbox is running. **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 -- `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**: -`CommandHandle` handle to interact with the running command +`True` if the sandbox is running, `False` otherwise +Example +```python +sandbox = Sandbox() +sandbox.is_running() # Returns True + +sandbox.kill() +sandbox.is_running() # Returns False +``` #### connect ```python -def connect(pid: int, - timeout: Optional[float] = 60, - request_timeout: Optional[float] = None) +@classmethod +def connect(cls, + sandbox_id: str, + api_key: Optional[str] = None, + domain: Optional[str] = None, + debug: Optional[bool] = None) ``` -Connects to a running command. +Connects to an existing Sandbox. -You can use `CommandHandle.wait()` to wait for the command to finish and get execution results. +With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). **Arguments**: -- `pid`: Process ID of the command to connect to. You can get the list of processes using `sandbox.commands.list()` -- `timeout`: Timeout for the connection in **seconds**. Using `0` will not limit the connection time -- `request_timeout`: Timeout for the request in **seconds** +- `sandbox_id`: Sandbox ID +- `api_key`: E2B API Key to use for authentication, defaults to `E2B_API_KEY` environment variable **Returns**: -`CommandHandle` handle to interact with the running command - +sandbox instance for the existing sandbox +@example +```python +sandbox = Sandbox() +sandbox_id = sandbox.sandbox_id +same_sandbox = Sandbox.connect(sandbox_id) -## CommandHandle +#### kill ```python -class CommandHandle() +@overload +def kill(request_timeout: Optional[float] = None) -> bool ``` -Command execution handle. - -It provides methods for waiting for the command to finish, retrieving stdout/stderr, and killing the command. +Kill the sandbox. +**Arguments**: -#### pid +- `request_timeout`: Timeout for the request in **seconds** -```python -@property -def pid() -``` +**Returns**: -Command process ID. +`True` if the sandbox was killed, `False` if the sandbox was not found -#### \_\_iter\_\_ +#### kill ```python -def __iter__() +@overload +@staticmethod +def kill(sandbox_id: str, + api_key: Optional[str] = None, + domain: Optional[str] = None, + debug: Optional[bool] = None, + request_timeout: Optional[float] = None) -> bool ``` -Iterate over the command output. - -**Returns**: - -Generator of command outputs - +Kill the sandbox specified by sandbox ID. -#### disconnect +**Arguments**: -```python -def disconnect() -> None -``` +- `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** -Disconnect from the command. +**Returns**: -The command is not killed, but SDK stops receiving events from the command. -You can reconnect to the command using `sandbox.commands.connect` method. +`True` if the sandbox was killed, `False` if the sandbox was not found -#### wait +#### kill ```python -def wait(on_pty: Optional[Callable[[PtyOutput], None]] = None, - on_stdout: Optional[Callable[[str], None]] = None, - on_stderr: Optional[Callable[[str], None]] = None) -> CommandResult +@class_method_variant("_cls_kill") +def kill(request_timeout: Optional[float] = None) -> bool ``` -Wait for the command to finish and returns the result. - -If the command exits with a non-zero exit code, it throws a `CommandExitException`. +Kill the sandbox. **Arguments**: -- `on_pty`: Callback for pty output -- `on_stdout`: Callback for stdout output -- `on_stderr`: Callback for stderr output +- `request_timeout`: Timeout for the request **Returns**: -`CommandResult` result of command execution +`True` if the sandbox was killed, `False` if the sandbox was not found -#### kill +#### set\_timeout ```python -def kill() -> bool +@overload +def set_timeout(timeout: int, request_timeout: Optional[float] = None) -> None ``` -Kills the command. - -It uses `SIGKILL` signal to kill the command. +Set the timeout of the sandbox. -**Returns**: +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`. -Whether the command was killed successfully +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** -## Pty +#### set\_timeout ```python -class Pty() +@overload +@staticmethod +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) -> None ``` -Module for interacting with PTYs (pseudo-terminals) in the sandbox. - - -#### kill +Set the timeout of the sandbox specified by sandbox ID. -```python -def kill(pid: int, request_timeout: Optional[float] = None) -> bool -``` +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`. -Kill PTY. +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**: -- `pid`: Process ID of the PTY +- `sandbox_id`: Sandbox ID +- `timeout`: Timeout for the sandbox in **seconds** +- `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**: -`true` if the PTY was killed, `false` if the PTY was not found -#### send\_stdin +## Filesystem ```python -def send_stdin(pid: int, - data: bytes, - request_timeout: Optional[float] = None) -> None +class Filesystem() ``` -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** +Module for interacting with the filesystem in the sandbox. -#### create +#### read ```python -def create(size: PtySize, - user: Username = "user", - cwd: Optional[str] = None, - envs: Optional[Dict[str, str]] = None, - timeout: Optional[float] = 60, - request_timeout: Optional[float] = None) -> CommandHandle +@overload +def read(path: str, + format: Literal["text"] = "text", + user: Username = "user", + request_timeout: Optional[float] = None) -> str ``` -Start a new PTY (pseudo-terminal). +Read file content as a `str`. **Arguments**: -- `size`: Size of the PTY -- `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** +- `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**: -Handle to interact with the PTY +File content as a `str` -#### resize +#### read ```python -def resize(pid: int, - size: PtySize, - request_timeout: Optional[float] = None) -> None +@overload +def read(path: str, + format: Literal["bytes"], + user: Username = "user", + request_timeout: Optional[float] = None) -> bytearray ``` -Resize PTY. - -Call this when the terminal window is resized and the number of columns and rows has changed. +Read file content as a `bytearray`. **Arguments**: -- `pid`: Process ID of the PTY -- `size`: New size of the PTY -- `request_timeout`: Timeout for the request in **seconds**s - - - +- `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** -## SandboxApi +**Returns**: -```python -class SandboxApi(SandboxApiBase) -``` +File content as a `bytearray` -#### list +#### read ```python -@classmethod -def list(cls, - api_key: Optional[str] = None, - domain: Optional[str] = None, - debug: Optional[bool] = None, - request_timeout: Optional[float] = None) -> List[SandboxInfo] +@overload +def read(path: str, + format: Literal["stream"], + user: Username = "user", + request_timeout: Optional[float] = None) -> Iterator[bytes] ``` -List all running sandboxes. +Read file content as a `Iterator[bytes]`. **Arguments**: -- `api_key`: API key to use for authentication, defaults to `E2B_API_KEY` environment variable +- `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**: -List of sandbox info - - +File content as an `Iterator[bytes]` -## Sandbox +#### write ```python -class Sandbox(SandboxSetup, SandboxApi) +def write(path: str, + data: Union[str, bytes, IO], + user: Username = "user", + request_timeout: Optional[float] = None) -> EntryInfo ``` -E2B cloud sandbox is a secure and isolated cloud environment. +Write content to a file on the path. -The sandbox allows you to: -- Access Linux OS -- Create, list, and delete files and directories -- Run commands -- Run isolated code -- Access the internet +Writing to a file that doesn't exist creates the file. -Check docs [here](https://e2b.dev/docs). +Writing to a file that already exists overwrites the file. -Use the `Sandbox()` to create a new sandbox. +Writing to a file at path that doesn't exist creates the necessary directories. -**Example**: +**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** -```python -from e2b import Sandbox +**Returns**: -sandbox = Sandbox() -``` +Information about the written file -#### files +#### list ```python -@property -def files() -> Filesystem +def list(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> List[EntryInfo] ``` -Module for interacting with the sandbox filesystem. +List entries in a directory. +**Arguments**: -#### commands +- `path`: Path to the directory +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request in **seconds** -```python -@property -def commands() -> Commands -``` +**Returns**: -Module for running commands in the sandbox. +List of entries in the directory -#### pty +#### exists ```python -@property -def pty() -> Pty +def exists(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> bool ``` -Module for interacting with the sandbox pseudo-terminal. +Check if a file or a directory exists. +**Arguments**: -#### sandbox\_id +- `path`: Path to a file or a directory +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request in **seconds** -```python -@property -def sandbox_id() -> str -``` +**Returns**: -Unique identifier of the sandbox +`True` if the file or directory exists, `False` otherwise -#### \_\_init\_\_ +#### remove ```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) +def remove(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> None ``` -Create a new sandbox. - -By default, the sandbox is created from the default `base` sandbox template. +Remove a file or a directory. **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 +- `path`: Path to a file or a directory +- `user`: Run the operation as this user - `request_timeout`: Timeout for the request in **seconds** -**Returns**: - -sandbox instance for the new sandbox - -#### is\_running +#### rename ```python -def is_running(request_timeout: Optional[float] = None) -> bool +def rename(old_path: str, + new_path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> EntryInfo ``` -Check if the sandbox is running. +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**: -`True` if the sandbox is running, `False` otherwise -Example -```python -sandbox = Sandbox() -sandbox.is_running() # Returns True - -sandbox.kill() -sandbox.is_running() # Returns False -``` +Information about the renamed file or directory -#### connect +#### make\_dir ```python -@classmethod -def connect(cls, - sandbox_id: str, - api_key: Optional[str] = None, - domain: Optional[str] = None, - debug: Optional[bool] = None) +def make_dir(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> bool ``` -Connects to an existing Sandbox. - -With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). +Create a new directory and all directories along the way if needed on the specified path. **Arguments**: -- `sandbox_id`: Sandbox ID -- `api_key`: E2B API Key to use for authentication, defaults to `E2B_API_KEY` environment variable +- `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**: -sandbox instance for the existing sandbox -@example -```python -sandbox = Sandbox() -sandbox_id = sandbox.sandbox_id - -same_sandbox = Sandbox.connect(sandbox_id) +`True` if the directory was created, `False` if the directory already exists -#### kill +#### watch\_dir ```python -@overload -def kill(request_timeout: Optional[float] = None) -> bool +def watch_dir(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> WatchHandle ``` -Kill the sandbox. +Watch directory for filesystem events. **Arguments**: +- `path`: Path to a directory to watch +- `user`: Run the operation as this user - `request_timeout`: Timeout for the request in **seconds** **Returns**: -`True` if the sandbox was killed, `False` if the sandbox was not found +`WatchHandle` object for stopping watching directory -#### kill + + +## WatchHandle ```python -@overload -@staticmethod -def kill(sandbox_id: str, - api_key: Optional[str] = None, - domain: Optional[str] = None, - debug: Optional[bool] = None, - request_timeout: Optional[float] = None) -> bool +class WatchHandle() ``` -Kill the sandbox specified by sandbox ID. +Handle for watching filesystem events. +It is used to get the latest events that have occurred in the watched directory. -**Arguments**: +Use `.stop()` to stop watching the directory. -- `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** -**Returns**: +#### stop -`True` if the sandbox was killed, `False` if the sandbox was not found +```python +def stop() +``` + +Stop watching the directory. +After you stop the watcher you won't be able to get the events anymore. -#### kill +#### get\_new\_events ```python -@class_method_variant("_cls_kill") -def kill(request_timeout: Optional[float] = None) -> bool +def get_new_events() -> List[FilesystemEvent] ``` -Kill the sandbox. +Get the latest events that have occurred in the watched directory since the last call, or from the beginning of the watching, up until now. -**Arguments**: +**Returns**: -- `request_timeout`: Timeout for the request +List of filesystem events -**Returns**: -`True` if the sandbox was killed, `False` if the sandbox was not found -#### set\_timeout +## Commands ```python -@overload -def set_timeout(timeout: int, request_timeout: Optional[float] = None) -> None +class Commands() ``` -Set the timeout of the sandbox. +Module for executing commands in 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. +#### list + +```python +def list(request_timeout: Optional[float] = None) -> List[ProcessInfo] +``` + +Lists all running commands and PTY sessions. **Arguments**: -- `timeout`: Timeout for the sandbox in **seconds** - `request_timeout`: Timeout for the request in **seconds** +**Returns**: + +List of running commands and PTY sessions -#### set\_timeout + +#### kill ```python -@overload -@staticmethod -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) -> None +def kill(pid: int, request_timeout: Optional[float] = None) -> bool ``` -Set the timeout of the sandbox specified by sandbox ID. - -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`. +Kills a running command specified by its process ID. -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. +It uses `SIGKILL` signal to kill the command. **Arguments**: -- `sandbox_id`: Sandbox ID -- `timeout`: Timeout for the sandbox in **seconds** -- `api_key`: E2B API Key to use for authentication, defaults to `E2B_API_KEY` environment variable +- `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 -## Filesystem +#### send\_stdin ```python -class Filesystem() +def send_stdin(pid: int, data: str, request_timeout: Optional[float] = None) ``` -Module for interacting with the filesystem in the sandbox. +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** -#### read + +#### run ```python @overload -def read(path: str, - format: Literal["text"] = "text", - user: Username = "user", - request_timeout: Optional[float] = None) -> str +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[Callable[[str], None]] = None, + on_stderr: Optional[Callable[[str], None]] = None, + timeout: Optional[float] = 60, + request_timeout: Optional[float] = None) -> CommandResult ``` -Read file content as a `str`. +Start a new command and wait until it finishes executing. **Arguments**: -- `path`: Path to the file -- `user`: Run the operation as this user -- `format`: Format of the file content—`text` by default +- `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**: -File content as a `str` +`CommandResult` result of the command execution -#### read +#### run ```python @overload -def read(path: str, - format: Literal["bytes"], - user: Username = "user", - request_timeout: Optional[float] = None) -> bytearray +def run(cmd: str, + background: Literal[True], + envs: Optional[Dict[str, str]] = None, + user: Username = "user", + cwd: Optional[str] = None, + on_stdout: None = None, + on_stderr: None = None, + timeout: Optional[float] = 60, + request_timeout: Optional[float] = None) -> CommandHandle ``` -Read file content as a `bytearray`. +Start a new command and return a handle to interact with it. **Arguments**: -- `path`: Path to the file -- `user`: Run the operation as this user -- `format`: Format of the file content—`bytes` +- `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 +- `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**: -File content as a `bytearray` +`CommandHandle` handle to interact with the running command -#### read +#### connect ```python -@overload -def read(path: str, - format: Literal["stream"], - user: Username = "user", - request_timeout: Optional[float] = None) -> Iterator[bytes] +def connect(pid: int, + timeout: Optional[float] = 60, + request_timeout: Optional[float] = None) ``` -Read file content as a `Iterator[bytes]`. +Connects to a running command. + +You can use `CommandHandle.wait()` to wait for the command to finish and get execution results. **Arguments**: -- `path`: Path to the file -- `user`: Run the operation as this user -- `format`: Format of the file content—`stream` +- `pid`: Process ID of the command to connect to. You can get the list of processes using `sandbox.commands.list()` +- `timeout`: Timeout for the connection in **seconds**. Using `0` will not limit the connection time - `request_timeout`: Timeout for the request in **seconds** **Returns**: -File content as an `Iterator[bytes]` +`CommandHandle` handle to interact with the running command + -#### write + +## Pty ```python -def write(path: str, - data: Union[str, bytes, IO], - user: Username = "user", - request_timeout: Optional[float] = None) -> EntryInfo +class Pty() ``` -Write content to a file on the path. +Module for interacting with PTYs (pseudo-terminals) in the sandbox. -Writing to a file that doesn't exist creates the file. -Writing to a file that already exists overwrites the file. +#### kill -Writing to a file at path that doesn't exist creates the necessary directories. +```python +def kill(pid: int, request_timeout: Optional[float] = None) -> bool +``` + +Kill PTY. **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 +- `pid`: Process ID of the PTY - `request_timeout`: Timeout for the request in **seconds** **Returns**: -Information about the written file +`true` if the PTY was killed, `false` if the PTY was not found -#### list +#### send\_stdin ```python -def list(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> List[EntryInfo] +def send_stdin(pid: int, + data: bytes, + request_timeout: Optional[float] = None) -> None ``` -List entries in a directory. +Send input to a PTY. **Arguments**: -- `path`: Path to the directory -- `user`: Run the operation as this user +- `pid`: Process ID of the PTY +- `data`: Input data to send - `request_timeout`: Timeout for the request in **seconds** -**Returns**: - -List of entries in the directory - -#### exists +#### create ```python -def exists(path: str, +def create(size: PtySize, user: Username = "user", - request_timeout: Optional[float] = None) -> bool + cwd: Optional[str] = None, + envs: Optional[Dict[str, str]] = None, + timeout: Optional[float] = 60, + request_timeout: Optional[float] = None) -> CommandHandle ``` -Check if a file or a directory exists. +Start a new PTY (pseudo-terminal). **Arguments**: -- `path`: Path to a file or a directory -- `user`: Run the operation as this user +- `size`: Size of the PTY +- `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**: -`True` if the file or directory exists, `False` otherwise +Handle to interact with the PTY -#### remove +#### resize ```python -def remove(path: str, - user: Username = "user", +def resize(pid: int, + size: PtySize, request_timeout: Optional[float] = None) -> None ``` -Remove a file or a directory. +Resize PTY. + +Call this when the terminal window is resized and the number of columns and rows has changed. **Arguments**: -- `path`: Path to a file or a directory -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request in **seconds** +- `pid`: Process ID of the PTY +- `size`: New size of the PTY +- `request_timeout`: Timeout for the request in **seconds**s + -#### rename + +## CommandHandle ```python -def rename(old_path: str, - new_path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> EntryInfo +class CommandHandle() ``` -Rename a file or directory. +Command execution handle. -**Arguments**: +It provides methods for waiting for the command to finish, retrieving stdout/stderr, and killing the command. -- `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**: +#### pid -Information about the renamed file or directory +```python +@property +def pid() +``` +Command process ID. -#### make\_dir + +#### \_\_iter\_\_ ```python -def make_dir(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> bool +def __iter__() ``` -Create a new directory and all directories along the way if needed on the specified path. +Iterate over the command output. -**Arguments**: +**Returns**: -- `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** +Generator of command outputs -**Returns**: -`True` if the directory was created, `False` if the directory already exists +#### disconnect + +```python +def disconnect() -> None +``` +Disconnect from the command. -#### watch\_dir +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 -def watch_dir(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> WatchHandle +def wait(on_pty: Optional[Callable[[PtyOutput], None]] = None, + on_stdout: Optional[Callable[[str], None]] = None, + on_stderr: Optional[Callable[[str], None]] = None) -> CommandResult ``` -Watch directory for filesystem events. +Wait for the command to finish and returns the result. + +If the command exits with a non-zero exit code, it throws a `CommandExitException`. **Arguments**: -- `path`: Path to a directory to watch -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request in **seconds** +- `on_pty`: Callback for pty output +- `on_stdout`: Callback for stdout output +- `on_stderr`: Callback for stderr output **Returns**: -`WatchHandle` object for stopping watching directory - - +`CommandResult` result of command execution -## WatchHandle +#### kill ```python -class WatchHandle() +def kill() -> bool ``` -Handle for watching filesystem events. -It is used to get the latest events that have occurred in the watched directory. +Kills the command. -Use `.stop()` to stop watching the directory. +It uses `SIGKILL` signal to kill the command. +**Returns**: -#### stop +Whether the command was killed successfully + + + + +## SandboxApi ```python -def stop() +class SandboxApi(SandboxApiBase) ``` -Stop watching the directory. -After you stop the watcher you won't be able to get the events anymore. - -#### get\_new\_events +#### list ```python -def get_new_events() -> List[FilesystemEvent] +@classmethod +def list(cls, + api_key: Optional[str] = None, + domain: Optional[str] = None, + debug: Optional[bool] = None, + request_timeout: Optional[float] = None) -> List[SandboxInfo] ``` -Get the latest events that have occurred in the watched directory since the last call, or from the beginning of the watching, up until now. +List all running sandboxes. + +**Arguments**: + +- `api_key`: API key to use for authentication, defaults to `E2B_API_KEY` environment variable +- `request_timeout`: Timeout for the request in **seconds** **Returns**: -List of filesystem events +List of sandbox info diff --git a/packages/js-sdk/package.json b/packages/js-sdk/package.json index 14afe1e04..200551306 100644 --- a/packages/js-sdk/package.json +++ b/packages/js-sdk/package.json @@ -1,6 +1,6 @@ { "name": "e2b", - "version": "1.0.4", + "version": "1.0.5", "description": "E2B SDK that give agents cloud environments", "homepage": "https://e2b.dev", "license": "MIT",