Skip to main content
Agent file systems provide persistent, isolated storage that survives across sessions, enabling complex workflows with data persistence and file management.

​
Overview

The File System primitive gives agents the ability to create, read, write, and manage files within their execution environment. Each agent session has access to a complete Linux file system with persistent storage, allowing agents to:
  • Store Data: Save files, datasets, configurations, and artifacts
  • Process Files: Read, modify, and transform file contents
  • Organize Content: Create directory structures and manage file hierarchies
  • Persist State: Maintain files across multiple requests in the same session
  • Generate Outputs: Create reports, code files, images, and other deliverables

Full Read/Write Access

Complete file system operations - create, read, update, delete files and directories

10GB Storage

Each session gets 10GB of persistent disk space

Session Persistence

Files remain available across all requests in the same session

Automatic Management

Agents handle file operations automatically based on your instructions

​
How File Systems Work

Agents use specialized tools to interact with the file system:

​
Core File Tools

The primary tool for file operations. Provides:
  • Create: Create new files with content
  • View: Read file contents
  • Edit: Modify files using find-and-replace
  • Insert: Add content at specific locations
  • Undo: Revert recent changes
// Agent automatically uses str_replace_editor
const result = await agentbase.runAgent({
  message: "Create a file called config.json with database settings"
});
Shell commands for file manipulation:
  • Copy: cp source dest
  • Move: mv source dest
  • Delete: rm file
  • List: ls -la
  • Permissions: chmod, chown
const result = await agentbase.runAgent({
  message: "Copy all .txt files to the backup folder"
});
Find files matching patterns:
  • Pattern matching: *.js, **/*.ts
  • Recursive search: **/test/*.py
  • Multiple patterns: {*.json,*.yaml}
const result = await agentbase.runAgent({
  message: "Find all Python files in the project"
});
Search for text within files:
  • Regex patterns: grep "pattern" file
  • Recursive search: grep -r "pattern" .
  • Case-insensitive: grep -i "pattern"
const result = await agentbase.runAgent({
  message: "Find all TODO comments in the codebase"
});

​
File System Architecture

​
Directory Structure

The default working directory is /home/pointer: 
/home/pointer/          # Default working directory
├── .cache/             # Cache directory
├── .config/            # Configuration files
├── .local/             # User-local data
└── [your files]        # Created by agent

​
Storage Hierarchy

​
Code Examples

​
Creating Files

// Create a single file
const result = await agentbase.runAgent({
  message: "Create a file called hello.py with a simple hello world program"
});

// Create multiple files
const multi = await agentbase.runAgent({
  message: "Create a React project structure with App.js, index.js, and package.json"
});

// Create file with specific content
const config = await agentbase.runAgent({
  message: `Create config.json with this content:
  {
    "apiKey": "xxx",
    "endpoint": "https://api.example.com"
  }`
});

​
Reading Files

// Read file contents
const read = await agentbase.runAgent({
  message: "Read the contents of data.csv and summarize it"
});

// Read multiple files
const readMulti = await agentbase.runAgent({
  message: "Read all .md files in the docs folder and create a table of contents"
});

// Read and process
const process = await agentbase.runAgent({
  message: "Read config.json and validate all required fields are present"
});

​
Modifying Files

// Edit existing file
const edit = await agentbase.runAgent({
  message: "Update the version number in package.json to 2.0.0",
  session: existingSession
});

// Find and replace
const replace = await agentbase.runAgent({
  message: "Replace all instances of 'oldFunction' with 'newFunction' in src/utils.js",
  session: existingSession
});

// Append to file
const append = await agentbase.runAgent({
  message: "Add a new route to routes.js for the profile page",
  session: existingSession
});

​
File Organization

// Create directory structure
const structure = await agentbase.runAgent({
  message: "Create folders for src, tests, and docs"
});

// Move files
const organize = await agentbase.runAgent({
  message: "Move all .js files to the src folder",
  session: structure.session
});

// Copy with organization
const backup = await agentbase.runAgent({
  message: "Create a backup folder and copy all important files there",
  session: structure.session
});

​
Searching Files

// Find files by pattern
const find = await agentbase.runAgent({
  message: "Find all TypeScript files in the project"
});

// Search content
const search = await agentbase.runAgent({
  message: "Search for all files containing 'API_KEY'"
});

// Complex search
const complexSearch = await agentbase.runAgent({
  message: "Find all Python test files that import the requests library"
});

​
Use Cases

​
1. Code Generation and Management

Generate complete projects with proper file organization: 
const project = await agentbase.runAgent({
  message: `Create a FastAPI project with:
  - main.py with basic setup
  - requirements.txt with dependencies
  - .env.example for configuration
  - README.md with setup instructions
  - tests/test_main.py with sample tests`
});

// All files persist in the session

​
2. Data Processing Workflows

Process data files and generate reports: 
// Step 1: Upload data (in practice, you'd create the file)
const upload = await agentbase.runAgent({
  message: "Create a sample sales_data.csv with 100 rows of sales data"
});

// Step 2: Process
const process = await agentbase.runAgent({
  message: "Analyze sales_data.csv and create a summary report as report.md",
  session: upload.session
});

// Step 3: Visualize
const viz = await agentbase.runAgent({
  message: "Create a Python script to visualize the data and save charts as images",
  session: upload.session
});

// All files (CSV, report, scripts, charts) persist

​
3. Configuration Management

Manage configuration files across environments: 
const config = await agentbase.runAgent({
  message: `Create configuration files for dev, staging, and prod environments:
  - config/dev.json
  - config/staging.json
  - config/prod.json
  Each should have appropriate API endpoints and settings`
});

// Later, update configs
const update = await agentbase.runAgent({
  message: "Update the prod config to use the new API endpoint",
  session: config.session
});

​
4. Documentation Generation

Generate and maintain documentation: 
const docs = await agentbase.runAgent({
  message: `Read all Python files in src/ and generate API documentation:
  - docs/api.md with function signatures
  - docs/examples.md with usage examples
  - docs/index.md as main entry point`
});

​
5. File Transformations

Convert between file formats: 
const transform = await agentbase.runAgent({
  message: "Convert data.json to CSV format and save as data.csv"
});

const convert = await agentbase.runAgent({
  message: "Read all markdown files and convert them to HTML",
  session: transform.session
});

​
Best Practices

​
File Naming and Organization

// Good: Clear, descriptive names
const result = await agentbase.runAgent({
  message: "Create customer_analysis_report.md"
});

// Avoid: Generic or unclear names
const result = await agentbase.runAgent({
  message: "Create file1.txt"
});

// Good: Organized structure
const result = await agentbase.runAgent({
  message: `Create organized structure:
  - src/ for source code
  - tests/ for test files
  - docs/ for documentation
  - data/ for data files`
});

// Avoid: Everything in root
const result = await agentbase.runAgent({
  message: "Create 20 files in the main folder"
});

// Good: Follow standard conventions
const result = await agentbase.runAgent({
  message: `Create Python project:
  - __init__.py
  - setup.py
  - requirements.txt
  - README.md`
});

​
Session Management

Persist Files Across Requests: Always use the same session ID when working with files that need to persist across multiple agent requests.
// Create files in first request
const create = await agentbase.runAgent({
  message: "Create data.json and processor.py"
});

// Access files in subsequent requests
const process = await agentbase.runAgent({
  message: "Run processor.py on data.json",
  session: create.session  // Critical!
});

​
Storage Management

Monitor and manage your 10GB storage limit: 
// Check disk usage
const check = await agentbase.runAgent({
  message: "Check disk usage and list the largest files"
});

// Clean up when needed
const cleanup = await agentbase.runAgent({
  message: "Delete temporary files and cache folders",
  session: check.session
});

​
Error Handling

Handle file-related errors gracefully: 
const result = await agentbase.runAgent({
  message: `Read config.json. If it doesn't exist, create a default one with:
  {
    "apiKey": "",
    "endpoint": "https://api.example.com"
  }`
});

​
Integration with Other Primitives

​
With Sandbox

Files exist within the sandbox environment: 
// Files are isolated per sandbox/session
const session1 = await agentbase.runAgent({
  message: "Create secret.txt with password"
});

const session2 = await agentbase.runAgent({
  message: "Create secret.txt with different password"
});

// Each session has its own secret.txt
Learn more: Sandbox Primitive

​
With Computer

Use bash commands for advanced file operations: 
const result = await agentbase.runAgent({
  message: "Use bash to find all files larger than 1MB and compress them"
});
Learn more: Computer Primitive

​
With Browser

Save web content to files: 
const result = await agentbase.runAgent({
  message: "Navigate to example.com, extract the data, and save it to data.json"
});
Learn more: Browser Primitive

​
With Custom Tools

Create files as tool outputs: 
const result = await agentbase.runAgent({
  message: "Use the weather API to get forecasts and save to forecast.json"
});
Learn more: Custom Tools

​
Performance Considerations

​
File Size Limits

  • Individual Files: No strict limit, but large files consume storage quota
  • Total Storage: 10GB per session
  • Read Performance: Files under 10MB read instantly
  • Write Performance: Optimized for files under 100MB

​
Optimization Tips

Batch Operations

Group file operations together to reduce overhead

Stream Large Files

Process large files in chunks rather than loading entirely

Clean Temporary Files

Remove temp files after processing to free space

Compress Archives

Compress large datasets to save storage

​
Performance Example

// Efficient: Process large file in chunks
const efficient = await agentbase.runAgent({
  message: "Read large_data.csv in chunks of 1000 rows and process each chunk"
});

// Inefficient: Loading entire large file
const inefficient = await agentbase.runAgent({
  message: "Load all of large_data.csv into memory and process"
});

​
Common File Operations

​
Working with Different File Types

// Create JSON
const create = await agentbase.runAgent({
  message: 'Create data.json with {"users": [], "settings": {}}'
});

// Read and modify JSON
const modify = await agentbase.runAgent({
  message: "Add a new user to data.json",
  session: create.session
});

// Validate JSON
const validate = await agentbase.runAgent({
  message: "Validate that data.json is valid JSON",
  session: create.session
});

// Create CSV
const csv = await agentbase.runAgent({
  message: "Create sales.csv with columns: date, product, amount"
});

// Process CSV
const process = await agentbase.runAgent({
  message: "Read sales.csv and calculate total sales by product",
  session: csv.session
});

// Convert CSV
const convert = await agentbase.runAgent({
  message: "Convert sales.csv to JSON format",
  session: csv.session
});

// Create and write
const write = await agentbase.runAgent({
  message: "Create notes.txt with a list of tasks"
});

// Read and search
const search = await agentbase.runAgent({
  message: "Search notes.txt for tasks containing 'urgent'",
  session: write.session
});

// Append
const append = await agentbase.runAgent({
  message: "Add a new task to notes.txt",
  session: write.session
});

// Create source files
const code = await agentbase.runAgent({
  message: "Create a Python module utils.py with helper functions"
});

// Modify code
const modify = await agentbase.runAgent({
  message: "Add error handling to all functions in utils.py",
  session: code.session
});

// Test code
const test = await agentbase.runAgent({
  message: "Create test_utils.py to test the functions",
  session: code.session
});

// Download and save
const download = await agentbase.runAgent({
  message: "Download image from URL and save as logo.png"
});

// Process binary
const process = await agentbase.runAgent({
  message: "Resize logo.png to 200x200 pixels",
  session: download.session
});

​
Advanced Patterns

​
Multi-File Workflows

// Complex project setup
const project = await agentbase.runAgent({
  message: `Create a full-stack project:

  Backend (backend/):
  - app.py with Flask setup
  - requirements.txt
  - config.py
  - models/user.py
  - routes/api.py

  Frontend (frontend/):
  - index.html
  - style.css
  - app.js
  - package.json

  Root:
  - README.md
  - .gitignore
  - docker-compose.yml`
});

​
Incremental File Building

// Start with base
const base = await agentbase.runAgent({
  message: "Create base.py with common utilities"
});

// Add features incrementally
const feature1 = await agentbase.runAgent({
  message: "Add logging functionality to base.py",
  session: base.session
});

const feature2 = await agentbase.runAgent({
  message: "Add configuration loading to base.py",
  session: base.session
});

const feature3 = await agentbase.runAgent({
  message: "Add error handling decorators to base.py",
  session: base.session
});

​
File-Based State Management

// Use files to track state
const init = await agentbase.runAgent({
  message: "Create state.json to track workflow progress: {step: 1, completed: []}"
});

// Update state after each step
const step2 = await agentbase.runAgent({
  message: "Complete step 1, update state.json to step 2",
  session: init.session
});

const step3 = await agentbase.runAgent({
  message: "Complete step 2, update state.json to step 3",
  session: init.session
});

​
Troubleshooting

Problem: Agent cannot find a fileSolutions:
  • Verify you’re using the correct session ID
  • Check file path and name (Linux is case-sensitive)
  • List directory contents to confirm file exists
const check = await agentbase.runAgent({
  message: "List all files in the current directory and show their paths",
  session: yourSession
});
Problem: Cannot read or write fileSolution: Files should be in /home/pointer directory with proper permissions
const fix = await agentbase.runAgent({
  message: "Check file permissions and fix any permission issues"
});
Problem: Reached 10GB storage limitSolutions:
  • Clean up temporary files
  • Compress large files
  • Start a new session if needed
const cleanup = await agentbase.runAgent({
  message: "Show disk usage, identify large files, and remove unnecessary ones"
});
Problem: File contents appear corruptedSolution: Verify file encoding and format
const verify = await agentbase.runAgent({
  message: "Check the encoding and format of data.json and repair if needed"
});

Sandbox

Isolated execution environment for files

Computer

Shell access for advanced file operations

Sessions

Session persistence for file continuity

Persistence

Understanding data persistence

​
Additional Resources

File Tools Reference

Complete tool documentation

API Examples

File operation examples

Best Practices

Production file management
File Persistence: Files persist within a session until the session expires or is deleted. For long-term storage, consider downloading files or using external storage solutions.