Sandbox file transfer

Have your machine ID and the local and guest paths ready before starting sandbox file transfer. Files created by remote commands stay on the machine until you download them.

Upload and download

Replace ID with your machine ID:

bead exec ID 'mkdir -p /root/project'
bead put ID /root/project/input.txt --input ./input.txt
bead get ID /root/project/input.txt --output ./retrieved.txt
bead exec ID 'wc -c /root/project/input.txt'

put uploads local bytes to the guest path. get downloads guest bytes. Each transfer is limited to 32 MiB. With --json, downloads require --output so binary bytes do not enter JSON.

Manage paths

bead files calls the native guest filesystem API. Supported operations are Stat, ListDir, MakeDir, Move, and Remove. For example, save this as list.json:

{"path":"/root/project","depth":1}

bead files ID ListDir --input list.json

Use get and put for file contents. Check the operation response before assuming a path changed.

Use MCP

Tool	Use
`bead:files`	Filesystem operations
`bead:file_write`	Write UTF-8 text, up to 64 KiB
`bead:file_download`	Obtain a short-lived authenticated download URI

Download handles expire after 600 seconds. The handle alone grants no access: the downloading HTTP client must send its bead bearer credential. Hosted MCP keeps guest transport credentials out of tool results. For large command output, use retained results. For local source trees with remote execution, use worktrees.

Get started

Use cases

Connect

Run work

Set up machines and templates

Snapshots and fork

Machines

Agents and computer use

Worktrees

Fleets and swarms

Teams and organizations

Security and data

Help

Sandbox file transfer

Upload and download

Manage paths

Use MCP

​Upload and download

​Manage paths

​Use MCP

Upload and download

Manage paths

Use MCP