Managed Files
Castari provides zero-configuration file storage for your agents. Upload files, attach them to agents, and they automatically appear in the sandbox.
Why Managed Files?
Your agents often need access to:
- Data files (CSV, JSON, etc.)
- Configuration files
- Documents for processing
- Reference materials
Managed files let you provide these simply without:
- Setting up cloud storage buckets
- Managing credentials
- Configuring mount paths manually
How It Works
- Upload — Files go to Castari’s managed storage
- Attach — Link files to specific agents
- Mount — Files automatically appear at
/files/agent/ in the sandbox
File Scopes
Files can be scoped for different uses:
| Scope | Description | Mount Path |
|---|
user | Your personal files | Available to attach |
agent | Attached to a specific agent | /files/agent/ |
session | Per-invocation outputs | /files/session/ |
Uploading Files
Via CLI
cast files upload data.csv --description "Training data"
Via Dashboard
- Navigate to Files in the sidebar
- Click Upload File
- Select file and add optional description/tags
Via SDK
const result = await client.files.upload(fileBlob, 'data.csv', {
description: 'Training data',
tags: ['dataset', 'csv'],
});
console.log(result.file_id); // file_abc123
Attaching Files to Agents
Once uploaded, attach files to agents:
Via CLI
cast agents files add my-agent file_abc123
Via Dashboard
- Go to Agents → your agent
- Find the Attached Files section
- Click Attach File and select from your files
Via SDK
await client.files.attachToAgent('my-agent', {
fileId: 'file_abc123',
readOnly: true,
});
Using Files in Agents
Attached files are available at /files/agent/:
import { readFileSync } from 'fs';
// Read attached file
const data = readFileSync('/files/agent/data.csv', 'utf-8');
// Parse and process
const rows = data.split('\n').map(line => line.split(','));
Files are read-only by default. Use --writable flag or set readOnly: false to allow writes.
Storage Limits
| Plan | Storage Limit |
|---|
| Free | 100 MB |
| Pro | 10 GB |
| Enterprise | Custom |
Total Files 12
Total Size 45.2 MB
Quota Used 45.2%
Quota Limit 100 MB
████████████████████░░░░░░░░░░░░░░░░░░░░ 45.2%
Managed vs. BYO Storage
Castari supports both managed files and bring-your-own storage buckets:
| Feature | Managed Files | BYO Buckets |
|---|
| Setup | Zero config | Configure credentials |
| Storage | Castari hosted | Your S3/GCS/R2 |
| Cost | Included in plan | Your cloud costs |
| Use case | Simple files | Large datasets |
Use managed files for simplicity. Use Storage Buckets for large datasets or when you need files in your own cloud.
- Filename — Original name
- Size — File size in bytes
- Content Type — MIME type
- SHA256 Hash — Integrity verification
- Description — Optional description
- Tags — Optional tags for organization
Best Practices
Organization
- Use descriptions — Document what each file is for
- Tag consistently — Use tags like
dataset, config, reference
- Clean up — Delete files you no longer need
Security
- Don’t upload secrets — Use Secrets for credentials
- Verify hashes — Check SHA256 for critical files
- Review attachments — Only attach files agents actually need
- Keep files small — For large datasets, use BYO storage
- Use appropriate formats — CSV/JSON for structured data
- Consider caching — Files are cached in the sandbox
See Also
