File Management

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)

stn files upload --key mydata/input.csv data.csv

stn files upload --ttl 24h report.pdf

stn files upload --station http://localhost:8585 data.csv

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

stn files download files/f_abc123

stn files download runs/run_xyz/output/result.csv -o result.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.

stn files list [flags]

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

stn files list

stn files list --prefix files/

stn files list --prefix runs/

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.

stn files info <file_key> [flags]

Flag	Description
`--station`	Station API URL

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.

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

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

Local vs Remote Mode

Local Mode
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

Requires NATS server running locally.

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

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:

# 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

Connection Failed

Error: failed to connect to NATS at nats://127.0.0.1:4222

Fix: Ensure NATS is running or set custom URL:

export WORKFLOW_NATS_URL=nats://your-nats-server:4222

File Not Found

Error: file not found: files/f_abc123

Fix: Verify the file key:

stn files list --prefix files/

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

Sandbox Execution

Learn about sandbox file staging tools

Workflows

Build multi-step agent pipelines

Get Started

Station CLI

Building Agents

Station Lattice

Deployment

Advanced

Overview

Commands

Upload

Download

List

Info

Delete

File Key Conventions

Local vs Remote Mode

Complete Example

Configuration

Environment Variables

Station Config

Troubleshooting

Next Steps

Sandbox Execution

Workflows

​Overview

​Commands

​Upload

​Download

​List

​Info

​Delete

​File Key Conventions

​Local vs Remote Mode

​Complete Example

​Configuration

​Environment Variables

​Station Config

​Troubleshooting

​Next Steps

Sandbox Execution

Workflows

Overview

Commands

Upload

Download

List

Info

Delete

File Key Conventions

Local vs Remote Mode

Complete Example

Configuration

Environment Variables

Station Config

Troubleshooting

Next Steps