Transfer files

Every sandbox exposes a filesystem API under /v1/sandbox/{sandbox_id}/fs. Read and write bodies are raw bytes — not tar archives, not multipart form data — so each call moves exactly one file. See Files for the full field reference; this guide is workflow-focused.

Upload a file

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 upload $SANDBOX_ID ./hello.txt /workspace/hello.txt

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

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

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

fs/write returns 204 with no body on success. The SDKs stream in 64 KiB chunks through a guest-side temp file and publish atomically, so a reader never observes a partially written file.

Download a file

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 download $SANDBOX_ID /workspace/hello.txt ./hello.downloaded.txt

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

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

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

fs/read returns the raw bytes as application/octet-stream — there’s no envelope to unwrap.

There’s no directory/tar transfer mode in this API. upload/download (CLI and SDKs) and fs/read/fs/write (REST) each move exactly one file. To move a directory tree, upload or download its files individually, or run a command via exec that packs/unpacks an archive on the sandbox side.

Write small content directly

For short text content you don’t want to stage as a local file first, read/write on the SDK take bytes or a string directly rather than a file path:

await sandbox.writeFile("/workspace/message.txt", "hello\n");
const payload = await sandbox.readFile("/workspace/message.txt");

sandbox.write_file("/workspace/message.txt", "hello\n")
payload = sandbox.read_file("/workspace/message.txt")

List a directory

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")

The response is { "files": [ ...FsFileInfo ] } — immediate children only, sorted by name, each carrying path, name, kind (FILE/DIRECTORY/SYMLINK/OTHER), size, mode, and modified_at_unix_nanos.

Stat a file

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");

info = sandbox.stat_file("/workspace/hello.txt")

stat returns lstat-style metadata — a symlink is reported as a symlink, not followed.

Directories, renaming, and deleting

# mkdir
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"}'

# rename
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"}'

# delete (recursive)
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 mkdir $SANDBOX_ID /workspace/output
bonya fs mv $SANDBOX_ID /workspace/hello.txt /workspace/output/hello.txt
bonya fs rm $SANDBOX_ID /workspace/output --recursive

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

sandbox.mkdir_file("/workspace/output")
sandbox.move_file("/workspace/hello.txt", "/workspace/output/hello.txt")
sandbox.remove_file("/workspace/output", recursive=True)

move/rename is same-filesystem and atomic — it doesn’t overwrite an existing destination, and won’t move across filesystems. remove with recursive set removes a non-empty directory without following symlinks.

Get started

Tutorials

Core concepts

API essentials

Guides

Transfer files

Upload a file

Download a file

Write small content directly

List a directory

Stat a file

Directories, renaming, and deleting

Files

Sandboxes

​Upload a file

​Download a file

​Write small content directly

​List a directory

​Stat a file

​Directories, renaming, and deleting

​Related

Files

Sandboxes

Upload a file

Download a file

Write small content directly

List a directory

Stat a file

Directories, renaming, and deleting

Related