# Volume (/v2.29.1/volume)

<!-- agent-signals: reading_time_min: 11 · est_tokens: 4651 · updated: 2026-07-30 -->
Related: [Errors](/v2.29.1/errors.md), [Sandbox](/v2.29.1/sandbox.md), [Sandbox Commands](/v2.29.1/sandbox-commands.md), [Sandbox Filesystem](/v2.29.1/sandbox-filesystem.md), [Template](/v2.29.1/template.md), [Template Logger](/v2.29.1/template-logger.md)

### VolumeFileType [#volumefiletype]

File type enum.

#### Enumeration Members [#enumeration-members]

| Enumeration Member               | Value         |
| -------------------------------- | ------------- |
| <a id="directory" /> `DIRECTORY` | `"directory"` |
| <a id="file" /> `FILE`           | `"file"`      |
| <a id="symlink" /> `SYMLINK`     | `"symlink"`   |
| <a id="unknown" /> `UNKNOWN`     | `"unknown"`   |

## Classes [#classes]

### Volume [#volume]

Module for interacting with E2B volumes.

Create a `Volume` instance to interact with a volume by its ID,
or use the static methods to manage volumes.

#### Constructors [#constructors]

```ts
new Volume(
   volumeId: string, 
   name: string, 
   token: string, 
   domain?: string, 
   debug?: boolean, 
   proxy?: string): Volume
```

Create a local Volume instance with no API call.

###### Parameters [#parameters]

| Parameter  | Type      | Description                           |
| ---------- | --------- | ------------------------------------- |
| `volumeId` | `string`  | volume ID.                            |
| `name`     | `string`  | volume name.                          |
| `token`    | `string`  | volume auth token.                    |
| `domain`?  | `string`  | domain for the volume API.            |
| `debug`?   | `boolean` | whether to use debug mode.            |
| `proxy`?   | `string`  | proxy URL for the volume content API. |

###### Returns [#returns]

`Volume`

#### Properties [#properties]

| Property                       | Modifier   | Type      | Description                                                      |
| ------------------------------ | ---------- | --------- | ---------------------------------------------------------------- |
| <a id="debug" /> `debug?`      | `readonly` | `boolean` | Whether to use debug mode (connects to local volume API server). |
| <a id="domain" /> `domain?`    | `readonly` | `string`  | Domain used for constructing the volume API URL.                 |
| <a id="name" /> `name`         | `readonly` | `string`  | Volume name.                                                     |
| <a id="proxy" /> `proxy?`      | `readonly` | `string`  | Proxy URL used for requests to the volume content API.           |
| <a id="token" /> `token`       | `readonly` | `string`  | Volume auth token.                                               |
| <a id="volumeid" /> `volumeId` | `readonly` | `string`  | Volume ID.                                                       |

#### Methods [#methods]

### exists() [#exists]

```ts
exists(path: string, opts?: VolumeApiOpts): Promise<boolean>
```

Check whether a file or directory exists.

Uses getInfo under the hood. Returns `true` if the path exists,
`false` if it does not (404). Other errors are rethrown.

###### Parameters [#parameters-1]

| Parameter | Type            | Description                    |
| --------- | --------------- | ------------------------------ |
| `path`    | `string`        | path to the file or directory. |
| `opts`?   | `VolumeApiOpts` | connection options.            |

###### Returns [#returns-1]

`Promise`\<`boolean`>

`true` if the path exists, `false` otherwise.

### getInfo() [#getinfo]

```ts
getInfo(path: string, opts?: VolumeApiOpts): Promise<VolumeEntryStat>
```

Get information about a file or directory.

###### Parameters [#parameters-2]

| Parameter | Type            | Description                    |
| --------- | --------------- | ------------------------------ |
| `path`    | `string`        | path to the file or directory. |
| `opts`?   | `VolumeApiOpts` | connection options.            |

###### Returns [#returns-2]

`Promise`\<`VolumeEntryStat`>

information about the entry.

### list() [#list]

```ts
list(path: string, opts?: VolumeApiOpts & object): Promise<VolumeEntryStat[]>
```

List directory contents.

###### Parameters [#parameters-3]

| Parameter | Type                       | Description            |
| --------- | -------------------------- | ---------------------- |
| `path`    | `string`                   | path to the directory. |
| `opts`?   | `VolumeApiOpts` & `object` | connection options.    |

###### Returns [#returns-3]

`Promise`\<`VolumeEntryStat`\[]>

list of entries in the directory.

### makeDir() [#makedir]

```ts
makeDir(path: string, opts?: VolumeMetadataOptions & object & VolumeApiOpts): Promise<VolumeEntryStat>
```

Create a directory.

###### Parameters [#parameters-4]

| Parameter | Type                                                 | Description                      |
| --------- | ---------------------------------------------------- | -------------------------------- |
| `path`    | `string`                                             | path to the directory to create. |
| `opts`?   | `VolumeMetadataOptions` & `object` & `VolumeApiOpts` | connection options.              |

###### Returns [#returns-4]

`Promise`\<`VolumeEntryStat`>

### readFile() [#readfile]

###### Call Signature [#call-signature]

```ts
readFile(path: string, opts?: VolumeApiOpts & object): 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 [#parameters-5]

| Parameter | Type                       | Description         |
| --------- | -------------------------- | ------------------- |
| `path`    | `string`                   | path to the file.   |
| `opts`?   | `VolumeApiOpts` & `object` | connection options. |

###### Returns [#returns-5]

`Promise`\<`string`>

file content as string

###### Call Signature [#call-signature-1]

```ts
readFile(path: string, opts?: VolumeApiOpts & object): Promise<Uint8Array<ArrayBufferLike>>
```

Read file content as a `Uint8Array`.

You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type.

###### Parameters [#parameters-6]

| Parameter | Type                       | Description         |
| --------- | -------------------------- | ------------------- |
| `path`    | `string`                   | path to the file.   |
| `opts`?   | `VolumeApiOpts` & `object` | connection options. |

###### Returns [#returns-6]

`Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

file content as `Uint8Array`

###### Call Signature [#call-signature-2]

```ts
readFile(path: string, opts?: VolumeApiOpts & object): 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 [#parameters-7]

| Parameter | Type                       | Description         |
| --------- | -------------------------- | ------------------- |
| `path`    | `string`                   | path to the file.   |
| `opts`?   | `VolumeApiOpts` & `object` | connection options. |

###### Returns [#returns-7]

`Promise`\<`Blob`>

file content as `Blob`

###### Call Signature [#call-signature-3]

```ts
readFile(path: string, opts?: VolumeApiOpts & object): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>
```

Read file content as a `ReadableStream`.

You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type.

###### Parameters [#parameters-8]

| Parameter | Type                       | Description         |
| --------- | -------------------------- | ------------------- |
| `path`    | `string`                   | path to the file.   |
| `opts`?   | `VolumeApiOpts` & `object` | connection options. |

###### Returns [#returns-8]

`Promise`\<`ReadableStream`\<`Uint8Array`\<`ArrayBufferLike`>>>

file content as `ReadableStream`

### remove() [#remove]

```ts
remove(path: string, opts?: VolumeApiOpts): Promise<void>
```

Remove a file or directory.

###### Parameters [#parameters-9]

| Parameter | Type            | Description                              |
| --------- | --------------- | ---------------------------------------- |
| `path`    | `string`        | path to the file or directory to remove. |
| `opts`?   | `VolumeApiOpts` | connection options.                      |

###### Returns [#returns-9]

`Promise`\<`void`>

### updateMetadata() [#updatemetadata]

```ts
updateMetadata(
   path: string, 
   metadata: VolumeMetadataOptions, 
opts?: VolumeApiOpts): Promise<VolumeEntryStat>
```

Update file or directory metadata.

###### Parameters [#parameters-10]

| Parameter  | Type                    | Description                          |
| ---------- | ----------------------- | ------------------------------------ |
| `path`     | `string`                | path to the file or directory.       |
| `metadata` | `VolumeMetadataOptions` | metadata to update (uid, gid, mode). |
| `opts`?    | `VolumeApiOpts`         | connection options.                  |

###### Returns [#returns-10]

`Promise`\<`VolumeEntryStat`>

updated entry information.

### writeFile() [#writefile]

```ts
writeFile(
   path: string, 
   data: 
  | string
  | ArrayBuffer
  | Blob
  | ReadableStream<Uint8Array<ArrayBufferLike>>, 
opts?: VolumeMetadataOptions & object & VolumeApiOpts): Promise<VolumeEntryStat>
```

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.

###### Parameters [#parameters-11]

| Parameter | Type                                                                                          | Description                                                                                  |
| --------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `path`    | `string`                                                                                      | path to the file.                                                                            |
| `data`    | \| `string` \| `ArrayBuffer` \| `Blob` \| `ReadableStream`\<`Uint8Array`\<`ArrayBufferLike`>> | data to write to the file. Data can be a string, `ArrayBuffer`, `Blob`, or `ReadableStream`. |
| `opts`?   | `VolumeMetadataOptions` & `object` & `VolumeApiOpts`                                          | connection options.                                                                          |

###### Returns [#returns-11]

`Promise`\<`VolumeEntryStat`>

information about the written file

### connect() [#connect]

```ts
static connect(volumeId: string, opts?: ConnectionOpts): Promise<Volume>
```

Connect to an existing volume by ID.

###### Parameters [#parameters-12]

| Parameter  | Type             | Description         |
| ---------- | ---------------- | ------------------- |
| `volumeId` | `string`         | volume ID.          |
| `opts`?    | `ConnectionOpts` | connection options. |

###### Returns [#returns-12]

`Promise`\<`Volume`>

Volume instance.

### create() [#create]

```ts
static create(name: string, opts?: ConnectionOpts): Promise<Volume>
```

Create a new volume.

###### Parameters [#parameters-13]

| Parameter | Type             | Description         |
| --------- | ---------------- | ------------------- |
| `name`    | `string`         | name of the volume. |
| `opts`?   | `ConnectionOpts` | connection options. |

###### Returns [#returns-13]

`Promise`\<`Volume`>

new Volume instance.

### destroy() [#destroy]

```ts
static destroy(volumeId: string, opts?: ConnectionOpts): Promise<boolean>
```

Destroy a volume.

###### Parameters [#parameters-14]

| Parameter  | Type             | Description         |
| ---------- | ---------------- | ------------------- |
| `volumeId` | `string`         | volume ID.          |
| `opts`?    | `ConnectionOpts` | connection options. |

###### Returns [#returns-14]

`Promise`\<`boolean`>

### getInfo() [#getinfo-1]

```ts
static getInfo(volumeId: string, opts?: ConnectionOpts): Promise<VolumeAndToken>
```

Get volume information.

###### Parameters [#parameters-15]

| Parameter  | Type             | Description         |
| ---------- | ---------------- | ------------------- |
| `volumeId` | `string`         | volume ID.          |
| `opts`?    | `ConnectionOpts` | connection options. |

###### Returns [#returns-15]

`Promise`\<`VolumeAndToken`>

volume information.

### list() [#list-1]

```ts
static list(opts?: ConnectionOpts): Promise<VolumeInfo[]>
```

List all volumes.

###### Parameters [#parameters-16]

| Parameter | Type             | Description         |
| --------- | ---------------- | ------------------- |
| `opts`?   | `ConnectionOpts` | connection options. |

###### Returns [#returns-16]

`Promise`\<`VolumeInfo`\[]>

list of volume information.

***

### VolumeConnectionConfig [#volumeconnectionconfig]

#### Constructors [#constructors-1]

```ts
new VolumeConnectionConfig(volume: Volume, opts?: VolumeApiOpts): VolumeConnectionConfig
```

###### Parameters [#parameters-17]

| Parameter | Type            |
| --------- | --------------- |
| `volume`  | `Volume`        |
| `opts`?   | `VolumeApiOpts` |

###### Returns [#returns-17]

`VolumeConnectionConfig`

#### Properties [#properties-1]

| Property                                        | Modifier   | Type                          |
| ----------------------------------------------- | ---------- | ----------------------------- |
| <a id="apiurl" /> `apiUrl`                      | `readonly` | `string`                      |
| <a id="debug-1" /> `debug`                      | `readonly` | `boolean`                     |
| <a id="domain-1" /> `domain`                    | `readonly` | `string`                      |
| <a id="headers" /> `headers?`                   | `readonly` | `Record`\<`string`, `string`> |
| <a id="logger" /> `logger?`                     | `readonly` | `Logger`                      |
| <a id="proxy-1" /> `proxy?`                     | `readonly` | `string`                      |
| <a id="requesttimeoutms" /> `requestTimeoutMs?` | `readonly` | `number`                      |
| <a id="signal" /> `signal?`                     | `readonly` | `AbortSignal`                 |
| <a id="token-1" /> `token?`                     | `readonly` | `string`                      |

#### Methods [#methods-1]

### getSignal() [#getsignal]

```ts
getSignal(requestTimeoutMs?: number, signal?: AbortSignal): undefined | AbortSignal
```

###### Parameters [#parameters-18]

| Parameter           | Type          |
| ------------------- | ------------- |
| `requestTimeoutMs`? | `number`      |
| `signal`?           | `AbortSignal` |

###### Returns [#returns-18]

`undefined` | `AbortSignal`

## Interfaces [#interfaces]

### VolumeApiOpts [#volumeapiopts]

#### Properties [#properties-2]

### domain? [#domain]

```ts
optional domain: string;
```

Domain to use for the volume API.

###### Default [#default]

E2B\_DOMAIN // environment variable or `e2b.app`

### headers? [#headers]

```ts
optional headers: Record<string, string>;
```

Additional headers to send with the request.

### logger? [#logger]

```ts
optional logger: Logger;
```

Logger to use for logging messages. It can accept any object that implements `Logger` interface—for example, console.

### proxy? [#proxy]

```ts
optional proxy: string;
```

Proxy URL to use for requests.

###### Example [#example]

```ts
'http://user:pass@127.0.0.1:8080'
```

### requestTimeoutMs? [#requesttimeoutms]

```ts
optional requestTimeoutMs: number;
```

Timeout for requests to the API in **milliseconds**.

###### Default [#default-1]

```ts
60_000 // 60 seconds
```

### signal? [#signal]

```ts
optional signal: AbortSignal;
```

An optional `AbortSignal` that can be used to cancel the in-flight request.
When the signal is aborted, the underlying `fetch` is aborted and the
returned promise rejects with an `AbortError`.

### token? [#token]

```ts
optional token: string;
```

E2B API key to use for authentication.

###### Default [#default-2]

```ts
E2B_API_KEY // environment variable
```

## Type Aliases [#type-aliases]

### VolumeAndToken [#volumeandtoken]

```ts
type VolumeAndToken = VolumeInfo & object;
```

Information about a volume and its auth token.

#### Type declaration [#type-declaration]

| Name    | Type     | Description        |
| ------- | -------- | ------------------ |
| `token` | `string` | Volume auth token. |

***

### VolumeEntryStat [#volumeentrystat]

```ts
type VolumeEntryStat = Omit<VolumeApiComponents["schemas"]["VolumeEntryStat"], "atime" | "mtime" | "ctime" | "type"> & object;
```

Volume entry stat with dates converted to Date objects.

#### Type declaration [#type-declaration-1]

| Name    | Type             | Description                         |
| ------- | ---------------- | ----------------------------------- |
| `atime` | `Date`           | Access time as a Date object.       |
| `ctime` | `Date`           | Creation time as a Date object.     |
| `mtime` | `Date`           | Modification time as a Date object. |
| `type`  | `VolumeFileType` | File type.                          |

***

### VolumeInfo [#volumeinfo]

```ts
type VolumeInfo = object;
```

Information about a volume.

#### Type declaration [#type-declaration-2]

| Name                             | Type     | Description  |
| -------------------------------- | -------- | ------------ |
| <a id="name-1" /> `name`         | `string` | Volume name. |
| <a id="volumeid-1" /> `volumeId` | `string` | Volume ID.   |

***

### VolumeMetadataOptions [#volumemetadataoptions]

```ts
type VolumeMetadataOptions = object;
```

Options for updating file metadata.

#### Type declaration [#type-declaration-3]

| Name                    | Type     | Description                        |
| ----------------------- | -------- | ---------------------------------- |
| <a id="gid" /> `gid`?   | `number` | Group ID of the file or directory. |
| <a id="mode" /> `mode`? | `number` | Mode of the file or directory.     |
| <a id="uid" /> `uid`?   | `number` | User ID of the file or directory.  |

***

### VolumeWriteOptions [#volumewriteoptions]

```ts
type VolumeWriteOptions = VolumeMetadataOptions & object;
```

Options for file and directory operations.

#### Type declaration [#type-declaration-4]

| Name     | Type      | Description                                                                                                     |
| -------- | --------- | --------------------------------------------------------------------------------------------------------------- |
| `force`? | `boolean` | For makeDir: Create parent directories if they don't exist. For writeFile: Force overwrite of an existing file. |