---
name: sandbox-files
description: "Use this skill whenever you need to share files with the user, save output files, or work with files the user has uploaded. The user's files live at /home/sandbox/files inside the sandbox. Any file you create, modify, or delete in that directory is immediately visible to the user and available for download. Always use this directory when producing deliverables (documents, images, code, data exports, etc.) or when reading files the user has provided."
---

# Sandbox Filesystem Collaboration

## Overview

The sandbox provides a shared directory at `/home/sandbox/files` for exchanging files with the user. This is the **only** directory the user can see and download from. Files placed anywhere else are invisible to them.

## Key Rules

1. **Always write output files to `/home/sandbox/files`.**
   Any file you want the user to have -- documents, images, scripts, data exports, archives -- must be saved there.

2. **Read user uploads from `/home/sandbox/files`.**
   When the user uploads files, they appear in this directory. Check here first when the user references a file.

3. **Changes are immediate.**
   Creating, modifying, or deleting a file in `/home/sandbox/files` is instantly reflected for the user. There is no publish or sync step.

4. **Use subdirectories when appropriate.**
   For tasks that produce many files, create a subdirectory (e.g., `/home/sandbox/files/exports/`) to keep things organized. The user can browse and download the entire tree.

5. **Clean up temporary artifacts.**
   If you create intermediate files the user does not need (e.g., temp build artifacts), either write them outside `/home/sandbox/files` or remove them when done.

6. **Deep link to files and folders.**
   You can link the user directly to any file or folder in their personal storage using the `?file=` query parameter to open it in the files panel, or the same link with `&download` appended to trigger a download. See Deep Linking below.

## Deep Linking

Use deep links whenever you produce a file the user should open or download — this saves them from having to navigate the file tree manually.

### Opening a file (or folder)

A relative link on the app's own host, using the `file` query parameter:

```
?file=<relative-path-from-storage-root>
```

| Intent | Link |
|--------|------|
| Open a file | `?file=report.pdf` |
| Open a file in a subfolder | `?file=exports/summary.csv` |
| Open a folder | `?file=charts` |

### Downloading a file

The **same** relative `?file=` link used to open a file, on the app's own host, with `&download` appended:

```
?file=<relative-path-from-storage-root>&download
```

Do **not** link directly to the user-store API's download endpoint (e.g. an absolute URL on an `api.` host) — the app's chat UI only knows how to attach authentication to the relative `?file=` deep link; a direct API link opened in a new tab will fail with 401 Unauthorized.

| Intent | Link |
|--------|------|
| Download a file | `?file=report.pdf&download` |
| Download a file in a subfolder | `?file=exports/summary.csv&download` |
| Download a file with spaces in the name | `?file=My+Quarterly+Report.xlsx&download` |

After writing a file, always provide the user with the appropriate deep link so they can open or download it in one click.

## Examples

```bash
# List what the user has uploaded
ls /home/sandbox/files

# Save a generated report for the user
cp report.pdf /home/sandbox/files/report.pdf

# Write a file directly
echo "Hello" > /home/sandbox/files/greeting.txt

# Create an organized output directory
mkdir -p /home/sandbox/files/charts
python generate_charts.py --output /home/sandbox/files/charts/
```

```python
import shutil, os

OUTPUT_DIR = "/home/sandbox/files"

# Read an uploaded file
with open(os.path.join(OUTPUT_DIR, "data.csv")) as f:
    data = f.read()

# Write results back for the user
with open(os.path.join(OUTPUT_DIR, "results.json"), "w") as f:
    f.write(results_json)
```

## Quick Reference

| Action | Path / Syntax |
|--------|---------------|
| Read user uploads | `/home/sandbox/files/<filename>` |
| Save output for user | `/home/sandbox/files/<filename>` |
| Organize many outputs | `/home/sandbox/files/<subfolder>/` |
| Temporary/intermediate files | Anywhere **outside** `/home/sandbox/files` |
| Deep link to open a file | `?file=<path>` |
| Deep link to download a file | `?file=<path>&download` |
