> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Virtual File System

> Isolated filesystem for file operations during task execution

## Usage

DeepAgent provides an isolated virtual filesystem. Files persist across the task execution and can be stored in memory (ephemeral) or persistent storage.

## Filesystem Tools

### ls

List directory contents.

```python theme={null}
ls(path: str = "/") -> str
```

### read\_file

Read file content with pagination.

```python theme={null}
read_file(file_path: str, offset: int = None, limit: int = 500) -> str
```

### write\_file

Create or overwrite a file.

```python theme={null}
write_file(file_path: str, content: str) -> str
```

### edit\_file

Perform exact string replacement.

```python theme={null}
edit_file(file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> str
```

**Important:** You must read a file before editing it.

### glob

Find files matching a pattern.

```python theme={null}
glob(pattern: str) -> str
```

**Pattern Examples:**

* `"*.txt"` - All text files in root
* `"/docs/**/*.md"` - All markdown files under /docs/
* `"/**/*.py"` - All Python files recursively

### grep

Search for text within files.

```python theme={null}
grep(
    pattern: str,
    path: str = "/",
    glob_pattern: str = None,
    output_mode: str = "files_with_matches",
    max_results: int = 100
) -> str
```

## Example

```python theme={null}
import asyncio
from upsonic.agent.deepagent import DeepAgent
from upsonic import Task

async def main():
    agent = DeepAgent(model="anthropic/claude-sonnet-4-5")
    
    task = Task(description="""
    Create a file /workspace/notes.txt with content "Initial notes"
    Then read the file
    Then edit it to change "Initial" to "Updated"
    List all files in /workspace/
    """)
    
    result = await agent.do_async(task)
    print(result)
    
    # Verify file exists
    exists = await agent.filesystem_backend.exists("/workspace/notes.txt")
    print(f"\nFile exists: {exists}")
    
    if exists:
        content = await agent.filesystem_backend.read("/workspace/notes.txt")
        print(f"File content: {content}")

asyncio.run(main())
```

## Advanced Example

```python theme={null}
import asyncio
from upsonic.agent.deepagent import DeepAgent
from upsonic import Task

async def main():
    agent = DeepAgent(model="anthropic/claude-sonnet-4-5")
    
    task = Task(description="""
    Create multiple files:
    1. /docs/python.md with content about Python
    2. /docs/javascript.md with content about JavaScript
    3. /scripts/helper.py with Python code
    
    Then:
    4. Find all .md files
    5. Find all files under /docs/
    6. Search for "Python" in all files
    7. Show matching lines with content output mode
    """)
    
    result = await agent.do_async(task)
    print(result)
    
    # List all files
    all_files = await agent.filesystem_backend.glob("/**/*")
    print(f"\nAll files: {all_files}")

asyncio.run(main())
```