> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentbase.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# File System
> Persistent file storage and management for agent workflows
> 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
Complete file system operations - create, read, update, delete files and directories
Each session gets 10GB of persistent disk space
Files remain available across all requests in the same session
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
```typescript theme={null}
// 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`
```typescript theme={null}
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}`
```typescript theme={null}
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"`
```typescript theme={null}
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
```mermaid theme={null}
graph TB
A[Session] --> B["File System"]
B --> C["/home/pointer"]
C --> D["User Files"]
C --> E["Installed Packages"]
C --> F["Generated Outputs"]
D --> G["Persistent Storage"]
E --> G
F --> G
G --> H["10GB Limit"]
```
## Code Examples
### Creating Files
```typescript TypeScript theme={null}
// 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"
}`
});
```
```python Python theme={null}
# 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
```typescript TypeScript theme={null}
// 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"
});
```
```python Python theme={null}
# 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
```typescript TypeScript theme={null}
// 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
});
```
```python Python theme={null}
# 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
```typescript TypeScript theme={null}
// 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
});
```
```python Python theme={null}
# 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
```typescript TypeScript theme={null}
// 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"
});
```
```python Python theme={null}
# 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:
```typescript theme={null}
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:
```typescript theme={null}
// 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:
```typescript theme={null}
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:
```typescript theme={null}
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:
```typescript theme={null}
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
```typescript theme={null}
// 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"
});
```
```typescript theme={null}
// 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"
});
```
```typescript theme={null}
// 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.
```typescript theme={null}
// 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:
```typescript theme={null}
// 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:
```typescript theme={null}
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:
```typescript theme={null}
// 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](/primitives/environment/sandbox)
### With Computer
Use bash commands for advanced file operations:
```typescript theme={null}
const result = await agentbase.runAgent({
message: "Use bash to find all files larger than 1MB and compress them"
});
```
Learn more: [Computer Primitive](/primitives/environment/computer)
### With Browser
Save web content to files:
```typescript theme={null}
const result = await agentbase.runAgent({
message: "Navigate to example.com, extract the data, and save it to data.json"
});
```
Learn more: [Browser Primitive](/primitives/environment/browser)
### With Custom Tools
Create files as tool outputs:
```typescript theme={null}
const result = await agentbase.runAgent({
message: "Use the weather API to get forecasts and save to forecast.json"
});
```
Learn more: [Custom Tools](/primitives/essentials/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
Group file operations together to reduce overhead
Process large files in chunks rather than loading entirely
Remove temp files after processing to free space
Compress large datasets to save storage
### Performance Example
```typescript theme={null}
// 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
```typescript theme={null}
// 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
});
```
```typescript theme={null}
// 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
});
```
```typescript theme={null}
// 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
});
```
```typescript theme={null}
// 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
});
```
```typescript theme={null}
// 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
```typescript theme={null}
// 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
```typescript theme={null}
// 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
```typescript theme={null}
// 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 file
**Solutions**:
* Verify you're using the correct session ID
* Check file path and name (Linux is case-sensitive)
* List directory contents to confirm file exists
```typescript theme={null}
const check = await agentbase.runAgent({
message: "List all files in the current directory and show their paths",
session: yourSession
});
```
**Problem**: Cannot read or write file
**Solution**: Files should be in `/home/pointer` directory with proper permissions
```typescript theme={null}
const fix = await agentbase.runAgent({
message: "Check file permissions and fix any permission issues"
});
```
**Problem**: Reached 10GB storage limit
**Solutions**:
* Clean up temporary files
* Compress large files
* Start a new session if needed
```typescript theme={null}
const cleanup = await agentbase.runAgent({
message: "Show disk usage, identify large files, and remove unnecessary ones"
});
```
**Problem**: File contents appear corrupted
**Solution**: Verify file encoding and format
```typescript theme={null}
const verify = await agentbase.runAgent({
message: "Check the encoding and format of data.json and repair if needed"
});
```
## Related Primitives
Isolated execution environment for files
Shell access for advanced file operations
Session persistence for file continuity
Understanding data persistence
## Additional Resources
Complete tool documentation
File operation examples
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.