> ## 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

<Info>
  File staging bypasses LLM context entirely—no token costs, no size limits, full binary support.
</Info>

## 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         |

<CodeGroup>
  ```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
  ```
</CodeGroup>

### 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  |

<CodeGroup>
  ```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
  ```
</CodeGroup>

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

### 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      |

<CodeGroup>
  ```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
  ```
</CodeGroup>

**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

<Tabs>
  <Tab title="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>

  <Tab title="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.
  </Tab>
</Tabs>

## 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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="File Not Found">
    ```
    Error: file not found: files/f_abc123
    ```

    **Fix:** Verify the file key:

    ```bash theme={null}
    stn files list --prefix files/
    ```
  </Accordion>

  <Accordion title="File Too Large">
    ```
    Error: file exceeds maximum size of 100 MB
    ```

    **Fix:** Increase `storage.max_file_size` in config or split the file.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Sandbox Execution" icon="box" href="/station/sandbox">
    Learn about sandbox file staging tools
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/station/workflows">
    Build multi-step agent pipelines
  </Card>
</CardGroup>