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

# File Management

> Upload, download, and manage files for sandbox staging

The `stn files` commands manage files in NATS Object Store for staging data to/from sandbox containers.

## Overview

Files serve as a staging area between your local system and sandbox containers:

1. **Upload** files from local filesystem
2. **Agents stage** files into sandbox using `sandbox_stage_file`
3. **Agents process** data in the sandbox
4. **Agents publish** results using `sandbox_publish_file`
5. **Download** results to local filesystem

> [!NOTE]
>
> File staging bypasses LLM context entirely—no token costs, no size limits, full binary support.

## Commands

### Upload

Upload a file to NATS Object Store.

```bash theme={null}
stn files upload <path> [flags]
```

| Flag | Description |
| - | - |
| `--key` | Custom file key (default: auto-generated) |
| `--ttl` | Time-to-live (e.g., `24h`, `7d`) |
| `--station` | Station API URL for remote upload |

```bash Basic theme={null}
stn files upload data.csv
# Output: files/f_01JGXYZ123ABC (2.4 MB)
```

```bash Custom Key theme={null}
stn files upload --key mydata/input.csv data.csv
```

```bash With Expiration theme={null}
stn files upload --ttl 24h report.pdf
```

```bash Remote Station theme={null}
stn files upload --station http://localhost:8585 data.csv
```

### Download

Download a file from the object store.

```bash theme={null}
stn files download <file_key> [flags]
```

| Flag | Short | Description |
| - | - | - |
| `--output` | `-o` | Output file path |
| `--station` | | Station API URL |

```bash Basic theme={null}
stn files download f_abc123 -o output.csv
```

```bash Full Key theme={null}
stn files download files/f_abc123
```

```bash Workflow Output theme={null}
stn files download runs/run_xyz/output/result.csv -o result.csv
```

> [!TIP]
>
> You can use either the full key (`files/f_abc123`) or just the file ID (`f_abc123`)—it auto-expands.

### List

List files in the object store.

```bash theme={null}
stn files list [flags]
```

| Flag | Description |
| - | - |
| `--prefix` | Filter by key prefix |
| `--json` | Output as JSON |
| `--station` | Station API URL |

```bash All Files theme={null}
stn files list
```

```bash User Uploads Only theme={null}
stn files list --prefix files/
```

```bash Workflow Outputs theme={null}
stn files list --prefix runs/
```

```bash JSON Output theme={null}
stn files list --json
```

**Example output:**

```
📁 Files
Found 3 file(s):

• files/f_01JGABC123DEF
    Size: 2.4 MB | Type: text/csv | Created: 2025-01-15 10:30
• files/f_01JGXYZ789UVW
    Size: 128 KB | Type: application/json | Created: 2025-01-15 11:45
• runs/run_abc/output/summary.csv
    Size: 64 KB | Type: text/csv | Created: 2025-01-15 12:00
    Expires: 2025-01-22 12:00
```

### Info

Show metadata for a file.

```bash theme={null}
stn files info <file_key> [flags]
```

| Flag | Description |
| - | - |
| `--station` | Station API URL |

```bash theme={null}
stn files info f_abc123
```

**Output:**

```
ℹ️  File Info
Key: files/f_01JGABC123DEF
Size: 2.4 MB
Content-Type: text/csv
Checksum: sha256:abc123...
Created: 2025-01-15T10:30:00Z
```

### Delete

Delete a file from the object store.

```bash theme={null}
stn files delete <file_key> [flags]
```

| Flag | Short | Description |
| - | - | - |
| `--force` | `-f` | Skip confirmation |
| `--station` | | Station API URL |

```bash theme={null}
# With confirmation
stn files delete f_abc123

# Skip confirmation
stn files delete f_abc123 --force
```

## File Key Conventions

Station uses a hierarchical key structure:

| Pattern | Description | Lifecycle |
| - | - | - |
| `files/{file_id}` | User uploads | Permanent until deleted |
| `runs/{run_id}/output/*` | Workflow outputs | Auto-cleanup after TTL |
| `sessions/{session_id}/*` | Session artifacts | Cleanup with session |

**File ID format:** `f_{ulid}` (time-ordered, globally unique)

## Local vs Remote Mode

> [tab] Local Mode
>
> Connects directly to NATS JetStream on the local machine.
>
> ```bash theme={null}
> # Uses WORKFLOW_NATS_URL (default: nats://127.0.0.1:4222)
> stn files upload data.csv
> stn files list
> ```
>
> Requires NATS server running locally.

> [tab] Remote Mode
>
> Connects to Station API via HTTP.
>
> ```bash theme={null}
> stn files upload --station http://remote:8585 data.csv
> stn files download --station http://remote:8585 f_abc -o out.csv
> ```
>
> Useful when Station runs on a remote server or you don't have direct NATS access.

## Complete Example

Process a large CSV file through a sandbox workflow:

```bash theme={null}
# 1. Upload input file (5 MB CSV)
$ stn files upload sales_data.csv
📤 Upload File
✅ Uploaded successfully
   Key: files/f_01JGABC123DEF
   Size: 5.2 MB
   Type: text/csv

# 2. Run workflow referencing the file
$ stn workflow run csv-analyzer \
    --input '{"input_file": "files/f_01JGABC123DEF"}'

# Workflow runs:
# - Agent opens sandbox
# - Agent stages file: sandbox_stage_file(file_key="files/f_01JGABC123DEF")
# - Agent processes with Python/pandas
# - Agent publishes: sandbox_publish_file(source="output/results.csv")
# Output: "Analysis complete. Results: files/f_01JGXYZ789UVW"

# 3. Download results
$ stn files download f_01JGXYZ789UVW -o analysis_results.csv
📥 Download File
✅ Downloaded successfully
   Output: analysis_results.csv
   Size: 128 KB
   Type: text/csv
```

## Configuration

### Environment Variables

| Variable | Default | Description |
| - | - | - |
| `WORKFLOW_NATS_URL` | `nats://127.0.0.1:4222` | NATS server for local mode |

### Station Config

```yaml theme={null}
storage:
  bucket: "sandbox-files"           # Object Store bucket
  max_file_size: 104857600          # 100 MB max file size
  max_total_bytes: 10737418240      # 10 GB total storage
  default_ttl: 0                    # No expiration by default
```

## Troubleshooting

> [accordion] Connection Failed
>
> ```
> Error: failed to connect to NATS at nats://127.0.0.1:4222
> ```
>
> **Fix:** Ensure NATS is running or set custom URL:
>
> ```bash theme={null}
> export WORKFLOW_NATS_URL=nats://your-nats-server:4222
> ```

> [accordion] File Not Found
>
> ```
> Error: file not found: files/f_abc123
> ```
>
> **Fix:** Verify the file key:
>
> ```bash theme={null}
> stn files list --prefix files/
> ```

> [accordion] File Too Large
>
> ```
> Error: file exceeds maximum size of 100 MB
> ```
>
> **Fix:** Increase `storage.max_file_size` in config or split the file.

## Next Steps

> [card] [Sandbox Execution](https://docs.cloudshipai.com/station/sandbox.md)
>
> Learn about sandbox file staging tools

> [card] [Workflows](https://docs.cloudshipai.com/station/workflows.md)
>
> Build multi-step agent pipelines


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