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:
- Upload files from local filesystem
- Agents stage files into sandbox using
sandbox_stage_file
- Agents process data in the sandbox
- Agents publish results using
sandbox_publish_file
- Download results to local filesystem
File staging bypasses LLM context entirely—no token costs, no size limits, full binary support.
Commands
Upload
Upload a file to NATS Object Store.
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 |
stn files upload data.csv
# Output: files/f_01JGXYZ123ABC (2.4 MB)
Download
Download a file from the object store.
stn files download <file_key> [flags]
| Flag | Short | Description |
|---|
--output | -o | Output file path |
--station | | Station API URL |
stn files download f_abc123 -o output.csv
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.
| Flag | Description |
|---|
--prefix | Filter by key prefix |
--json | Output as JSON |
--station | Station API URL |
📁 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.
stn files info <file_key> [flags]
| Flag | Description |
|---|
--station | Station API URL |
ℹ️ 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.
stn files delete <file_key> [flags]
| Flag | Short | Description |
|---|
--force | -f | Skip confirmation |
--station | | Station API URL |
# 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 |
f_{ulid} (time-ordered, globally unique)
Local vs Remote Mode
Connects directly to NATS JetStream on the local machine.# Uses WORKFLOW_NATS_URL (default: nats://127.0.0.1:4222)
stn files upload data.csv
stn files list
Connects to Station API via HTTP.stn files upload --station http://remote:8585 data.csv
stn files download --station http://remote:8585 f_abc -o out.csv
Complete Example
Process a large CSV file through a sandbox workflow:
# 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
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
Error: failed to connect to NATS at nats://127.0.0.1:4222
export WORKFLOW_NATS_URL=nats://your-nats-server:4222
Error: file not found: files/f_abc123
stn files list --prefix files/
Error: file exceeds maximum size of 100 MB
storage.max_file_size in config or split the file.Next Steps
