​

Managed Files

​

Why Managed Files?

• Data files (CSV, JSON, etc.)
• Configuration files
• Documents for processing
• Reference materials

• Setting up cloud storage buckets
• Managing credentials
• Configuring mount paths manually

​

How It Works

1. Upload — Files go to Castari’s managed storage
2. Attach — Link files to specific agents
3. Mount — Files automatically appear at /files/agent/ in the sandbox

​

File Scopes

​

Uploading Files

​

Via CLI

cast files upload data.csv --description "Training data"

​

Via Dashboard

1. Navigate to Files in the sidebar
2. Click Upload File
3. 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

​

Via CLI

cast agents files add my-agent file_abc123

​

Via Dashboard

1. Go to Agents → your agent
2. Find the Attached Files section
3. 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

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(','));

​

Storage Limits

cast files usage

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

████████████████████░░░░░░░░░░░░░░░░░░░░ 45.2%

​

Managed vs. BYO Storage

​

File Metadata

• 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

​

Performance

• 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