Managing Sandbox Files
Upload and download files and directories.
Render Sandboxes is in public beta.
APIs, defaults, and limits might change during the beta period.
After you create a sandbox, you can upload files and directories to it and download files it produces. Use these operations to provide code and input data, then retrieve results after executing commands.
Sandbox paths
When specifying a path inside a sandbox:
- Relative paths resolve from the sandbox's home directory. For example,
main.pyrefers to a file in that directory. - Absolute paths resolve from the sandbox's filesystem root. For example,
/tmp/output.jsonrefers to a file in/tmp.
Commands also start in the sandbox's home directory, so a file uploaded to main.py is available to a command like python main.py.
Uploading a file
The following example uploads a local file named main.py to the sandbox's home directory:
Call render sandboxes copy with the source and destination paths. Prefix the sandbox path with the sandbox's ID and a colon (:). You can also use cp as an alias for copy.
Call sandboxes.upload with the sandbox's ID, the destination path, and the file's contents. The contents can be a string, a Buffer, a Uint8Array, or a readable stream.
Call sandboxes.copy_to with the sandbox's ID, the local source path, and the destination path inside the sandbox.
Call sandboxes.copy_to with the sandbox's ID, the local source path, and the destination path inside the sandbox.
For a single file, provide the full destination path, including the filename. Uploading to an existing file replaces its contents.
Downloading a file
The following example downloads a file named output.json from the sandbox's home directory:
Reverse the source and destination order to download a file. If the local destination is an existing directory, the file is saved inside it with its original filename.
Call sandboxes.download with the sandbox's ID and the source path. The method returns an object with these fields:
| Field | Description |
|---|---|
|
|
The file's contents as a |
|
|
The number of downloaded bytes. |
|
|
The response's content type, if provided. |
The SDK enforces a default file size limit of 256 MB. If the download exceeds this limit, the SDK stops reading and throws a SandboxDownloadTooLargeError. Use writeFile to save the returned buffer to your local filesystem.
You can customize this file size limit. For details, see the SDK reference.
Call sandboxes.copy_from with the sandbox's ID, the source path inside the sandbox, and the local destination path. The method saves the file and returns the local path it wrote.
If the local destination is an existing directory, the file is saved inside it with its original filename.
Call sandboxes.copy_from with the sandbox's ID, the source path inside the sandbox, and the local destination path. The method saves the file and returns the local path it wrote.
If the local destination is an existing directory, the file is saved inside it with its original filename.
Transferring directories
You can transfer an entire directory, including its subdirectories. The directory's contents are placed directly inside the destination directory.
For example, if you upload the local directory ./src to your sandbox's ./app directory, a local file at ./src/main.py is uploaded to ./app/main.py inside the sandbox (not ./app/src/main.py).
Uploading a directory
The following example uploads the contents of a local src directory to a src directory inside the sandbox:
Provide a local directory as the source path. The CLI transfers its contents automatically. No recursive flag is required.
First, create a tar archive of the directory's contents on your local machine:
Then upload the archive with contentType set to application/x-tar. The sandbox extracts its contents into the destination directory:
The undefined parameter leaves the optional workspace ID unset so you can provide the upload options as the fifth parameter.
Provide a local directory as the source path. The SDK archives its contents and extracts them into the destination directory automatically.
Provide a local directory as the source path. The SDK archives its contents and extracts them into the destination directory automatically.
Downloading a directory
The following example downloads the contents of an output directory from the sandbox:
The CLI creates the local destination directory if needed and extracts the downloaded contents into it.
Downloading a directory returns its contents as a tar archive. Save the archive to your local filesystem:
The same download size limit applies to the entire tar archive.
Then extract it on your local machine:
The SDK creates the local destination directory if needed and extracts the downloaded contents into it.
The SDK creates the local destination directory if needed and extracts the downloaded contents into it.
Preserving files
Shared filesystems are in early access.
Use shared filesystems to give sandboxes access to storage that persists beyond their lifecycle. Attach a shared filesystem to multiple sandboxes so agents can work on the same data in parallel and preserve state across runs.
A sandbox keeps its files between commands and while suspended. When the sandbox terminates, its filesystem is deleted.
Download any files you need before termination. To reuse the sandbox's filesystem in new sandboxes, capture a snapshot.