Skip to content

docs: improve discoverability of storage options #687

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vikram-blaxel wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: improve discoverability of storage options #687

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions Agent-drive/Overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ Unlike [volumes](/Volumes/Overview), which are block storage devices attached at
- A specific subdirectory of a drive can be mounted using `drivePath` (instead of mounting the entire drive).
- Drives scale automatically with no fixed capacity limits. Pre-provisioning or run-time resizing is not required.

<Tip>
Refer to our [blog post on choosing the right storage for your Blaxel agents](https://blaxel.ai/blog/choose-the-right-storage-for-your-blaxel-agents) for more informaton.

@mendral-app mendral-app Bot Jul 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maintainability (P3): Typo: "informaton" should be "information". This same typo is repeated in Sandboxes/Filesystem.mdx:12, Sandboxes/best-practices.mdx:44, and Volumes/Overview.mdx:16.

Suggested change
Suggested change
Refer to our [blog post on choosing the right storage for your Blaxel agents](https://blaxel.ai/blog/choose-the-right-storage-for-your-blaxel-agents) for more informaton.
Refer to our [blog post on choosing the right storage for your Blaxel agents](https://blaxel.ai/blog/choose-the-right-storage-for-your-blaxel-agents) for more information.
Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At Agent-drive/Overview.mdx, line 22:

<issue>
Typo: "informaton" should be "information". This same typo is repeated in `Sandboxes/Filesystem.mdx:12`, `Sandboxes/best-practices.mdx:44`, and `Volumes/Overview.mdx:16`.
</issue>

</Tip>

## Use cases

Some examples of use cases are:
Expand Down
4 changes: 4 additions & 0 deletions Sandboxes/Filesystem.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ description: 'Read, write, list, and delete files inside a Blaxel sandbox using

Manage files and directories within sandboxes through the `fs` module of Blaxel SDK. This module provides essential operations for creating, reading, writing, copying, and deleting files and directories.

<Tip>
Refer to our [blog post on choosing the right storage for your Blaxel agents](https://blaxel.ai/blog/choose-the-right-storage-for-your-blaxel-agents) for more informaton.
</Tip>

<Tip>Complete code examples demonstrating all operations are available on Blaxel's GitHub: [in TypeScript](https://github.com/blaxel-ai/sdk-typescript/tree/main/tests/sandbox), [in Python](https://github.com/blaxel-ai/sdk-python/tree/main/tests/integration/sandbox), and [in Go](https://github.com/blaxel-ai/sdk-go/tree/main/integration_tests).</Tip>

## Basic file system operations
Expand Down
2 changes: 1 addition & 1 deletion Sandboxes/Overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,7 +252,7 @@ For write-heavy workloads, set `storageMb` (TypeScript/CLI) or `storage_mb` (Pyt

`storageMb` cannot be combined with a persistent volume mounted at `/`. Use root storage for ephemeral root filesystem capacity, or use a volume at a subpath such as `/data` when data should persist independently from the sandbox lifecycle.

Use [volumes](/Sandboxes/Volumes) when data needs to live at a specific mount path or persist independently from the sandbox lifecycle. Volumes require deleting and recreating the sandbox first, and are not as fast as the native in-memory filesystem.
Use [volumes](/Sandboxes/Volumes) when data needs to live at a specific mount path or persist independently from the sandbox lifecycle. Volumes require deleting and recreating the sandbox first, and are not as fast as the native in-memory filesystem. Refer to our [blog post on choosing the right storage for your Blaxel agents](https://blaxel.ai/blog/choose-the-right-storage-for-your-blaxel-agents) for more information.

### Ports

Expand Down
8 changes: 7 additions & 1 deletion Sandboxes/best-practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,16 @@ Here's a table to help you decide:
| Durability | Low (lost on sandbox deletion or crash) | High (block storage, replicated) | High (distributed storage, replicated)
| Access type | Single | Single | Multiple |
| Hot-attach | N/A | No | Yes |
| Interface | POSIX | POSIX | POSIX + S3 |
| Interface | POSIX | POSIX | POSIX (S3 interface coming soon) |
| Size | ~50% of sandbox memory by default; configurable with root storage | User-defined at creation, expandable | No size limit |
| Optimized for | Data that doesn’t require high durability | Data that requires durability with high performance | Shared data |

Refer to our [blog post on choosing the right storage for your Blaxel agents](https://blaxel.ai/blog/choose-the-right-storage-for-your-blaxel-agents) for more informaton.

<Note>
No storage option currently supports mounting external storage (such as S3 buckets) as a filesystem today via s3fs or similar (Agent Drive's S3 interface is planned but not yet available). There is also no built-in way to bulk-sync files between a sandbox and your local machine. Instead, use [`sandbox.fs.download()`](/Sandboxes/Filesystem#download-file-to-host) for single files, or the zip-upload-unzip pattern in the next section for bulk transfers.
</Note>

## Upload many files efficiently

Writing files one by one with `write()` costs one network round trip per file: at ~100ms per call, restoring several hundred files sequentially is minutes of pure latency.
Expand Down
4 changes: 4 additions & 0 deletions Volumes/Overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ While Blaxel automatically snapshots the full state of a sandbox at scale down a

Volumes use block storage and can only be accessed by attaching them to a running sandbox or agent. They cannot be mounted locally on your machine. Blaxel also does not support mounting external storage (such as S3 buckets) as volumes.

<Tip>
Refer to our [blog post on choosing the right storage for your Blaxel agents](https://blaxel.ai/blog/choose-the-right-storage-for-your-blaxel-agents) for more informaton.
</Tip>

## Create a volume

To create a standalone volume, you must provide a unique `name` and specify its `size` in megabytes (MB). You can also specify optional labels. This volume exists independently of any resource it may later be attached to.
Expand Down
2 changes: 1 addition & 1 deletion troubleshooting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ To resolve this error, choose the storage option that matches the workload:
- Add storage using [volumes](/Sandboxes/Volumes) when data should live at a specific mount path or persist independently from the sandbox lifecycle. Adding storage requires deleting and recreating the sandbox first.

<Note>
Volumes are slower than the in-memory filesystem.
Volumes are slower than the in-memory filesystem. Refer to our [blog post on choosing the right storage for your Blaxel agents](https://blaxel.ai/blog/choose-the-right-storage-for-your-blaxel-agents) for our benchmarks.
</Note>

## Sandbox commands return a `404 WORKSPACE_NOT_FOUND` error
Expand Down