Files

Every sandbox exposes a filesystem API under /v1/sandbox/{sandbox_id}/fs. All operations take a sandbox_id and, where they act on a path, a path query parameter.

Read and write bodies are raw bytes (application/octet-stream) — not tar archives, not multipart form data. Each call moves exactly one file’s contents.

Reading a file

GET /v1/sandbox/{sandbox_id}/fs/read

string

required

Path to the file.

Returns 200 with the raw file contents as application/octet-stream.

curl -s "https://api.bonya.ai/v1/sandbox/$SANDBOX_ID/fs/read?path=/workspace/hello.txt" \
  -H "Authorization: Bearer $BONYA_API_KEY" \
  -o ./hello.downloaded.txt

bonya fs read $SANDBOX_ID /workspace/hello.txt

const payload = await sandbox.readFile("/workspace/hello.txt");

payload = sandbox.read_file("/workspace/hello.txt")

payload, err := sandbox.ReadFile(ctx, "/workspace/hello.txt")

MCP: fs_read returns the file’s contents as a UTF-8 string, since MCP tool calls carry inline text rather than binary bytes.

Writing a file

PUT /v1/sandbox/{sandbox_id}/fs/write

string

required

Path to write to.

The request body is the raw file contents (application/octet-stream). Returns 204 on success — no response body.

curl -s -X PUT "https://api.bonya.ai/v1/sandbox/$SANDBOX_ID/fs/write?path=/workspace/hello.txt" \
  -H "Authorization: Bearer $BONYA_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./hello.txt

bonya fs write $SANDBOX_ID /workspace/hello.txt ./hello.txt

await sandbox.writeFile("/workspace/hello.txt", "hello\n");

sandbox.write_file("/workspace/hello.txt", "hello\n")

sandbox.WriteFile(ctx, "/workspace/hello.txt", []byte("hello\n"))

MCP: fs_write takes UTF-8 text content and creates or overwrites the file, returning { ok: true, path, bytes }.

Uploading and downloading a local file

There’s no dedicated REST endpoint for upload/download — the CLI and SDKs implement it as a local file streamed through the same raw-bytes fs/read and fs/write endpoints above.

bonya fs upload $SANDBOX_ID ./hello.txt /workspace/hello.txt
bonya fs download $SANDBOX_ID /workspace/hello.txt ./hello.downloaded.txt

await sandbox.uploadFile("./hello.txt", "/workspace/hello.txt");
await sandbox.downloadFile("/workspace/hello.txt", "./hello.downloaded.txt");

sandbox.upload_file("./hello.txt", "/workspace/hello.txt")
sandbox.download_file("/workspace/hello.txt", "./hello.downloaded.txt")

sandbox.UploadFile(ctx, "./hello.txt", "/workspace/hello.txt")
sandbox.DownloadFile(ctx, "/workspace/hello.txt", "./hello.downloaded.txt")

MCP: there’s no fs upload/download tool — MCP tool calls carry inline UTF-8 text, not binary file transfers, so fs_read/fs_write are the only way to move file contents through MCP.

Listing a directory

GET /v1/sandbox/{sandbox_id}/fs/list

string

required

Directory path to list.

Returns FsListResponse: { "files": [ ...FsFileInfo ] }.

curl -s "https://api.bonya.ai/v1/sandbox/$SANDBOX_ID/fs/list?path=/workspace" \
  -H "Authorization: Bearer $BONYA_API_KEY"

bonya fs ls $SANDBOX_ID /workspace

const entries = await sandbox.listFiles("/workspace");

entries = sandbox.list_files("/workspace")

entries, err := sandbox.ListFiles(ctx, "/workspace")

MCP: fs_list returns { files: [{ path, name, kind, size, mode, modified_at_unix_nanos }, ...] }.

Getting file metadata

GET /v1/sandbox/{sandbox_id}/fs/stat

string

required

Path to stat.

Returns FsStatResponse: { "file": { ...FsFileInfo } }.

curl -s "https://api.bonya.ai/v1/sandbox/$SANDBOX_ID/fs/stat?path=/workspace/hello.txt" \
  -H "Authorization: Bearer $BONYA_API_KEY"

bonya fs stat $SANDBOX_ID /workspace/hello.txt

const info = await sandbox.statFile("/workspace/hello.txt");
console.log(info.kind, info.size);

info = sandbox.stat_file("/workspace/hello.txt")
print(info.kind, info.size)

info, err := sandbox.StatFile(ctx, "/workspace/hello.txt")
fmt.Println(info.Kind, info.Size)

MCP: fs_stat returns { file: { path, name, kind, size, mode, modified_at_unix_nanos } }.

FsFileInfo fields

string

required

Full path.

string

required

Base name.

string

required

One of UNSPECIFIED, FILE, DIRECTORY, SYMLINK, OTHER.

integer

required

Size in bytes.

integer

required

Permission bits as reported by the guest, 0–4095.

integer

required

Last-modified time.

Creating a directory

POST /v1/sandbox/{sandbox_id}/fs/mkdir

Request body (FsMkdirRequest):

string

required

Directory path to create.

Returns 201 on success.

curl -s -X POST "https://api.bonya.ai/v1/sandbox/$SANDBOX_ID/fs/mkdir" \
  -H "Authorization: Bearer $BONYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/workspace/output"}'

bonya fs mkdir $SANDBOX_ID /workspace/output

await sandbox.mkdirFile("/workspace/output");

sandbox.mkdir_file("/workspace/output")

sandbox.MkdirFile(ctx, "/workspace/output")

MCP: fs_mkdir creates the directory (and any missing parents), returning { ok: true, path }.

Renaming or moving

POST /v1/sandbox/{sandbox_id}/fs/rename

Request body (FsRenameRequest):

string

required

Source path.

string

required

Destination path.

Returns 200 on success.

curl -s -X POST "https://api.bonya.ai/v1/sandbox/$SANDBOX_ID/fs/rename" \
  -H "Authorization: Bearer $BONYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "/workspace/hello.txt", "to": "/workspace/output/hello.txt"}'

bonya fs mv $SANDBOX_ID /workspace/hello.txt /workspace/output/hello.txt

await sandbox.moveFile("/workspace/hello.txt", "/workspace/output/hello.txt");

sandbox.move_file("/workspace/hello.txt", "/workspace/output/hello.txt")

sandbox.MoveFile(ctx, "/workspace/hello.txt", "/workspace/output/hello.txt")

MCP: fs_rename covers this, returning { ok: true, from, to }.

Deleting

DELETE /v1/sandbox/{sandbox_id}/fs

string

required

Path to remove.

boolean

default:"false"

Whether to remove a non-empty directory recursively.

Returns 204 on success.

curl -s -X DELETE "https://api.bonya.ai/v1/sandbox/$SANDBOX_ID/fs?path=/workspace/output&recursive=true" \
  -H "Authorization: Bearer $BONYA_API_KEY"

bonya fs rm $SANDBOX_ID /workspace/output --recursive

await sandbox.removeFile("/workspace/output", true);

sandbox.remove_file("/workspace/output", recursive=True)

sandbox.RemoveFile(ctx, "/workspace/output", true) // recursive

MCP: fs_delete covers this — pass recursive: true to delete a non-empty directory. Returns { ok: true, deleted: path }.

Get started

Tutorials

Core concepts

API essentials

Guides

Reading a file

Writing a file

Uploading and downloading a local file

Listing a directory

Getting file metadata

FsFileInfo fields

Creating a directory

Renaming or moving

Deleting

Sandboxes

Errors

​Reading a file

​Writing a file

​Uploading and downloading a local file

​Listing a directory

​Getting file metadata

​FsFileInfo fields

​Creating a directory

​Renaming or moving

​Deleting

​Related

Sandboxes

Errors

Reading a file

Writing a file

Uploading and downloading a local file

Listing a directory

Getting file metadata

FsFileInfo fields

Creating a directory

Renaming or moving

Deleting

Related