Clarify cloud file transfer limitations (#26499)

Document how cloud file transfers handle symbolic links and skip empty
directories. The transfer guidance explains when to use `-L` and that
directory downloads skip symbolic links even with that flag.

Validation: Markdown formatting and scoped rumdl/Vale lint passed with
no findings. Live cloud transfers were not tested.
This commit is contained in:
David Karlsson authored and GitHub committed 2026-11-04 09:58:32 +01:00
1 parent d40e4d2c02
commit 8f1a51e172
1 file changed
+9
@@ -158,6 +158,15 @@ $ sbx --cloud cp ./src cloud-project:/home/agent/workspace/src
$ sbx --cloud cp cloud-project:/home/agent/workspace/result.json ./result.json
```
Cloud copies don't preserve empty directories or symbolic links themselves.
Symbolic links are handled differently depending on the transfer:
- Uploading a symbolic link as the source copies its target automatically.
- Uploading a directory skips symbolic links inside it unless you pass
`-L` (`--follow-link`) to copy their targets.
- Downloading a symbolic link to a file requires `-L` to copy its target.
- Downloading a directory skips symbolic links, even with `-L`.
Copying creates a point-in-time transfer. It doesn't mount or synchronize the
local path. For source control workflows, you can also clone a remote
repository from inside the sandbox and push changes to the remote. Configure