> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox file transfer

> Upload inputs, download artifacts, and manage files with sandbox file transfer through the CLI, SDKs, or MCP.

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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
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`:

```json theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
{"path":"/root/project","depth":1}
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
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](https://docs.bead.run/run-work/output.md). For local source trees with remote execution, use [worktrees](https://docs.bead.run/worktrees/overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.