Working with Files

This guide covers how to provide files to your agents using Castari’s managed file storage.

Quick Start

# Upload a file
cast files upload data.csv

# Attach to agent
cast agents files add my-agent file_abc123

# Deploy agent
cast deploy my-agent

Your agent can now read the file at /files/agent/data.csv.

Uploading Files

CLI Upload

# Basic upload
cast files upload myfile.json

# With metadata
cast files upload data.csv --description "Customer data" --tags sales,2024

Dashboard Upload

Go to Files in the sidebar
Click Upload File
Drag & drop or select a file
Add optional description and tags
Click Upload

Large Files

Files larger than 10MB automatically use presigned uploads:

# Large file upload (handled automatically)
cast files upload large-dataset.parquet

The CLI shows progress for large uploads:

Uploading large-dataset.parquet (150 MB)...
████████████████████████████░░░░░░░░░░░░ 70%

Attaching Files to Agents

Basic Attachment

cast agents files add my-agent file_abc123

The file appears at /files/agent/<filename> in the sandbox.

Custom Mount Path

cast agents files add my-agent file_abc123 --mount-path /data/custom.csv

Writable Files

By default, files are read-only. For writable files:

cast agents files add my-agent file_abc123 --writable

Writable files can be modified by the agent. Use with caution.

Using Files in Agent Code

Reading Files

import { readFileSync, readFile } from 'fs';
import { readFile as asyncReadFile } from 'fs/promises';

// Synchronous read
const data = readFileSync('/files/agent/data.csv', 'utf-8');

// Async read
const asyncData = await asyncReadFile('/files/agent/data.csv', 'utf-8');

Parsing Common Formats

CSV:

import { parse } from 'csv-parse/sync';

const csvContent = readFileSync('/files/agent/data.csv', 'utf-8');
const records = parse(csvContent, { columns: true });

JSON:

const config = JSON.parse(
  readFileSync('/files/agent/config.json', 'utf-8')
);

Checking File Existence

import { existsSync } from 'fs';

if (existsSync('/files/agent/optional.txt')) {
  // File is available
}

Managing Files

List Your Files

# List all files
cast files list

# Filter by tags
cast files list --tags dataset

# Search by name
cast files list --search training

View File Details

cast files get file_abc123

Delete Files

cast files delete file_abc123

Deleting a file automatically detaches it from all agents.

Download Files

cast files download file_abc123 --output ./local-copy.csv

Agent File Management

List Attached Files

cast agents files list my-agent

File ID        Filename      Mount Path                Size      Mode
file_abc123    data.csv      /files/agent/data.csv     2.4 MB    ro
file_def456    config.json   /files/agent/config.json  1.2 KB    ro

Detach Files

cast agents files remove my-agent file_abc123

Dashboard File Management

Files Page

The Files page shows:

All your uploaded files
Storage usage bar
Quick search and filtering

Agent Files Section

Each agent’s detail page has an Attached Files section:

View attached files and mount paths
Attach new files with the file picker
Detach files you no longer need

Storage Usage

Check Your Quota

cast files usage

Total Files    12
Total Size     45.2 MB
Quota Used     45.2%
Quota Limit    100 MB

Storage Limits

Plan	Limit
Free	100 MB
Pro	10 GB
Enterprise	Custom

Best Practices

File Organization

Use meaningful names — customer-data-2024.csv not data.csv
Add descriptions — Document what each file is for
Tag consistently — Use tags like dataset, config, reference
Clean up unused files — Delete files you no longer need

Performance

Keep files reasonably sized — Under 100MB for best performance
Use appropriate formats — CSV/JSON for structured data
Consider streaming — For very large files, process in chunks

Security

Don’t upload secrets — Use Secrets for credentials
Review before attaching — Only attach files agents actually need
Verify file integrity — Check SHA256 hash for critical files

Common Patterns

Configuration Files

# Upload config
cast files upload agent-config.json --tags config

# Attach to agent
cast agents files add my-agent file_abc123

// In agent code
const config = JSON.parse(
  readFileSync('/files/agent/agent-config.json', 'utf-8')
);

Data Processing

# Upload dataset
cast files upload training-data.csv --tags dataset,ml

# Attach
cast agents files add ml-agent file_abc123

// In agent code
import { parse } from 'csv-parse/sync';

const csv = readFileSync('/files/agent/training-data.csv', 'utf-8');
const data = parse(csv, { columns: true });
// Process data...

Reference Documents

# Upload reference material
cast files upload product-docs.txt --tags reference,docs

# Attach
cast agents files add support-agent file_abc123

// In agent code
const docs = readFileSync('/files/agent/product-docs.txt', 'utf-8');
// Use in system prompt or for RAG

Troubleshooting

File Not Found

If your agent can’t find a file:

Verify the file is attached:
cast agents files list my-agent
Check the mount path in the output
Ensure you’re using the correct path in code

Upload Failures

For upload issues:

Check your storage quota:
cast files usage
Verify the file exists locally
For large files, ensure stable network connection

Permission Errors

If you get permission errors:

Files are read-only by default
Use --writable when attaching if writes are needed
Check file mode in cast agents files list

​Working with Files

​Quick Start

​Uploading Files

​CLI Upload

​Dashboard Upload

​Large Files

​Attaching Files to Agents

​Basic Attachment

​Custom Mount Path

​Writable Files

​Using Files in Agent Code

​Reading Files

​Parsing Common Formats

​Checking File Existence

​Managing Files

​List Your Files

​View File Details

​Delete Files

​Download Files

​Agent File Management

​List Attached Files

​Detach Files

​Dashboard File Management

​Files Page

​Agent Files Section

​Storage Usage

​Check Your Quota

​Storage Limits

​Best Practices

​File Organization

​Performance

​Security

​Common Patterns

​Configuration Files

​Data Processing

​Reference Documents

​Troubleshooting

​File Not Found

​Upload Failures

​Permission Errors

​See Also

Working with Files

Quick Start

Uploading Files

CLI Upload

Dashboard Upload

Large Files

Attaching Files to Agents

Basic Attachment

Custom Mount Path

Writable Files

Using Files in Agent Code

Reading Files

Parsing Common Formats

Checking File Existence

Managing Files

List Your Files

View File Details

Delete Files

Download Files

Agent File Management

List Attached Files

Detach Files

Dashboard File Management

Files Page

Agent Files Section

Storage Usage

Check Your Quota

Storage Limits

Best Practices

File Organization

Performance

Security

Common Patterns

Configuration Files

Data Processing

Reference Documents

Troubleshooting

File Not Found

Upload Failures

Permission Errors

See Also