File System - Agentbase Docs

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

str_replace_editor - File Creation and Editing

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"
});

bash - File Operations

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"
});

glob - File Search by Pattern

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"
});

grep - Content Search

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"
  }`
});

# Create a single file
result = agentbase.run_agent(
    message="Create a file called hello.py with a simple hello world program"
)

# Create multiple files
multi = agentbase.run_agent(
    message="Create a React project structure with App.js, index.js, and package.json"
)

# Create file with specific content
config = agentbase.run_agent(
    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"
});

# Read file contents
read = agentbase.run_agent(
    message="Read the contents of data.csv and summarize it"
)

# Read multiple files
read_multi = agentbase.run_agent(
    message="Read all .md files in the docs folder and create a table of contents"
)

# Read and process
process = agentbase.run_agent(
    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
});

# Edit existing file
edit = agentbase.run_agent(
    message="Update the version number in package.json to 2.0.0",
    session=existing_session
)

# Find and replace
replace = agentbase.run_agent(
    message="Replace all instances of 'oldFunction' with 'newFunction' in src/utils.js",
    session=existing_session
)

# Append to file
append = agentbase.run_agent(
    message="Add a new route to routes.js for the profile page",
    session=existing_session
)

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
});

# Create directory structure
structure = agentbase.run_agent(
    message="Create folders for src, tests, and docs"
)

# Move files
organize = agentbase.run_agent(
    message="Move all .js files to the src folder",
    session=structure.session
)

# Copy with organization
backup = agentbase.run_agent(
    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"
});

# Find files by pattern
find = agentbase.run_agent(
    message="Find all TypeScript files in the project"
)

# Search content
search = agentbase.run_agent(
    message="Search for all files containing 'API_KEY'"
)

# Complex search
complex_search = agentbase.run_agent(
    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

Use Descriptive Names

// 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"
});

Organize into Directories

// 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"
});

Follow Conventions

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

JSON Files

// 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
});

CSV Files

// 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
});

Text Files

// 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
});

Code Files

// 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
});

Binary Files

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

File Not Found

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
});

Permission Denied

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"
});

Disk Space Full

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"
});

File Corruption

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.

​Overview

Full Read/Write Access

10GB Storage

Session Persistence

Automatic Management

​How File Systems Work

​Core File Tools

​File System Architecture

​Directory Structure

​Storage Hierarchy

​Code Examples

​Creating Files

​Reading Files

​Modifying Files

​File Organization

​Searching Files

​Use Cases

​1. Code Generation and Management

​2. Data Processing Workflows

​3. Configuration Management

​4. Documentation Generation

​5. File Transformations

​Best Practices

​File Naming and Organization

​Session Management

​Storage Management

​Error Handling

​Integration with Other Primitives

​With Sandbox

​With Computer

​With Browser

​With Custom Tools

​Performance Considerations

​File Size Limits

​Optimization Tips

Batch Operations

Stream Large Files

Clean Temporary Files

Compress Archives

​Performance Example

​Common File Operations

​Working with Different File Types

​Advanced Patterns

​Multi-File Workflows

​Incremental File Building

​File-Based State Management

​Troubleshooting

​Related Primitives

Sandbox

Computer

Sessions

Persistence

​Additional Resources

File Tools Reference

API Examples

Best Practices

Overview

How File Systems Work

Core File Tools

File System Architecture

Directory Structure

Storage Hierarchy

Code Examples

Creating Files

Reading Files

Modifying Files

File Organization

Searching Files

Use Cases

1. Code Generation and Management

2. Data Processing Workflows

3. Configuration Management

4. Documentation Generation

5. File Transformations

Best Practices

File Naming and Organization

Session Management

Storage Management

Error Handling

Integration with Other Primitives

With Sandbox

With Computer

With Browser

With Custom Tools

Performance Considerations

File Size Limits

Optimization Tips

Performance Example

Common File Operations

Working with Different File Types

Advanced Patterns

Multi-File Workflows

Incremental File Building

File-Based State Management

Troubleshooting

Related Primitives

Additional Resources