Volumes
A VolumeA persistent volume that exists independently of any Workspace. A Workspace binds at most one Volume, mounted at /data by default. keeps a sandbox's data across pauses and after the sandbox is deleted. This page covers creating Volumes by name, mounting one in a sandbox, deleting it, and what queries return.
Overview
The gateway supports these Volume endpoints:
| Endpoint | Use |
|---|---|
POST /volumes | Create a standalone Volume by name, or get the existing one under that name |
GET /volumes | List Volumes |
GET /volumes/{id} | Get one Volume |
DELETE /volumes/{id} | Delete a Volume and its data |
- Each sandbox mounts at most one standalone Volume, with
volumeMountsat creation. - A sandbox created without
volumeMountsgets its own Volume at/data. Deleting the sandbox deletes that Volume and its data. - Deleting a sandbox does not delete a standalone Volume mounted with
volumeMounts. Delete that Volume explicitly. - A pause keeps the Volume. Write files you need to keep across a pause to it. See Pause and resume.
Creating a Volume by name
POST /volumes creates a standalone Volume by name. A name is held by only one Volume at a time, and the result depends on the newest Volume under that name that has not been deleted:
| Newest Volume under the name | Result of POST /volumes |
|---|---|
| None | Creates a new one and returns 201 |
| Available, mounted, or expanding | Returns it, 201 |
| Being created | Waits for creation to finish, then returns 201 |
| Creation failed | Deletes it and creates a new one. See Volumes that failed |
| Expansion or deletion failed | 409, with the Volume ID and the failure reason in the message |
| Result unknown | Replays the original create. If the result is still unknown, returns 409 with the reason in the message |
| Being deleted | 409 volume deletion is pending; retry later |
Repeating POST /volumes with the same name returns the same Volume while it is usable, so you can call it each time before creating a sandbox.
Mounting a Volume in a sandbox
Pass the Volume in volumeMounts when you create the sandbox. A sandbox mounts at most one standalone Volume.
When volumeMounts points at a failed Volume, the create returns 409, with the failure reason in the message. See Volumes that failed.
Volumes that failed
How a failed Volume is handled depends on whether it may hold data:
| Failure | May hold data | What happens |
|---|---|---|
| Creation failed | No. It was never usable | The next POST /volumes with the same name replaces it, without a prior delete |
| Expansion or deletion failed | Yes | The gateway does not delete it for you. POST /volumes with the name returns 409 |
When the next create replaces a Volume whose creation failed:
- It returns 201 if the new Volume is created.
- It returns 503 with a message containing
resource_exhaustedif capacity is still insufficient. Once capacity recovers, the same request returns 201. - For other failures it returns 409 or 502 depending on the reason, with the reason in the message.
To recreate a Volume whose expansion or deletion failed, first delete it with DELETE /volumes/{id}.
Deleting a Volume
DELETE /volumes/{id} deletes the Volume. Deleting a sandbox leaves its Volume in place, so delete Volumes you no longer need yourself.
Warning
Deleting a Volume discards its data.
Volume mounts in query results
GET /sandboxes/{id} and the list endpoint return volumeMounts with stable Volume names and mount paths.
GET /sandboxes/{id}returns 500 when the Volume has been deleted, is not in a usable state, or its mapping is incomplete, instead of wrongly reporting that the sandbox does not exist.- The list endpoint returns an empty
volumeMountsarray in the same situation. volumeMountsis the only field that the SDK's list call keeps. Read the other fields throughgetInfo(); see Sandbox information.
Next steps
- Sandboxes and lifecycle: pause, resume, and expiration.
- Commands and files: write files into the Volume.
- Volumes, export, and restore: how Volumes work for Workspaces.
Network
Control a sandbox's outbound access with the E2B SDK's allowInternetAccess and network create options, and change it later with sandbox.updateNetwork(). The gateway turns these settings into a Kibotos network policy, and can send the sandbox's outbound TCP through your own SOCKS5 proxy.
Metrics
The E2B SDK's sandbox.getMetrics() and Sandbox.getMetrics(id) return CPU, memory, and disk samples for a sandbox, as on E2B. This page covers the two metrics endpoints, the fields of each sample, and how time ranges and buckets work.