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

# Filesystem access

> Give agents the ability to read, write, and search files.

**Filesystem Tools** give agents a dedicated filesystem to save plans and take notes.

Agents read, write, search, and manage files with configurable isolation across
users and conversations.

Use filesystem tools for agents that:

* Store and retrieve user-specific data.
* Process documents and files.
* Maintain conversation-specific context.
* Generate reports or code files.

***

## Available Tools

When you add `FilesystemTools()` to an agent, these tools become available:

| Tool               | Description                                        |
| ------------------ | -------------------------------------------------- |
| `list_directory`   | List files and directories at a path               |
| `read_file`        | Read file contents, optionally by line range       |
| `write_file`       | Create or overwrite a file                         |
| `edit_file`        | Replace text in a file using exact string matching |
| `find_files`       | Find files matching a glob pattern                 |
| `search_in_files`  | Search for a regex pattern in files                |
| `remove_file`      | Delete a file                                      |
| `remove_directory` | Delete a directory                                 |

See [Available Operations](#available-operations) for detailed parameter documentation.

***

## Quick Start

Add filesystem tools to your agent with default (conversation-level) isolation:

```python images/main/main.py theme={null}
from autonomy import Agent, FilesystemTools, Model, Node


async def main(node):
  await Agent.start(
    node=node,
    name="assistant",
    instructions="You are a helpful assistant with file access",
    model=Model("claude-sonnet-4-v1"),
    tools=[FilesystemTools()]  # Default: conversation-level isolation
  )


Node.start(main)
```

The agent can now use filesystem operations:

```bash theme={null}
curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"message":"Create a file called notes.txt with the content: Hello World", "conversation":"chat-1"}' \
  "http://localhost:8000/agents/assistant"
```

Files isolate per conversation by default:

* Conversation `chat-1`: `/tmp/agent-files/assistant/default/chat-1/notes.txt`
* Conversation `chat-2`: `/tmp/agent-files/assistant/default/chat-2/notes.txt`

***

## Visibility Levels

Visibility controls file isolation between users and conversations. Choose the level that matches your security and sharing requirements.

### Conversation (Default)

**Maximum isolation** - Each conversation has its own isolated filesystem:

```python theme={null}
tools=[FilesystemTools(visibility="conversation")]
```

**Path structure:**

```
/tmp/agent-files/{agent_name}/{scope}/{conversation}/
```

**Example paths:**

```
User Alice, Chat 1: /tmp/agent-files/assistant/user-alice/chat-1/notes.txt
User Alice, Chat 2: /tmp/agent-files/assistant/user-alice/chat-2/notes.txt
User Bob, Chat 1:   /tmp/agent-files/assistant/user-bob/chat-1/notes.txt
```

**Use when:**

* Users must not see each other's files
* Different conversations must be completely isolated
* Maximum security is required
* Building chat applications with ephemeral workspaces

### Scope

**Per-user/tenant isolation** - Files shared across conversations for the same user:

```python theme={null}
tools=[FilesystemTools(visibility="scope")]
```

**Path structure:**

```
/tmp/agent-files/{agent_name}/{scope}/
```

**Example paths:**

```
User Alice, Chat 1: /tmp/agent-files/assistant/user-alice/notes.txt
User Alice, Chat 2: /tmp/agent-files/assistant/user-alice/notes.txt  # Same file!
User Bob, Chat 1:   /tmp/agent-files/assistant/user-bob/notes.txt
```

**Use when:**

* Users need persistent storage across conversations
* Building document management or note-taking apps
* Implementing user workspaces
* Multi-tenant applications with user isolation

### Agent

**Per-agent isolation** - Files shared across all users but separate per agent:

```python theme={null}
tools=[FilesystemTools(visibility="agent")]
```

**Path structure:**

```
/tmp/agent-files/{agent_name}/
```

**Example paths:**

```
All users, all conversations: /tmp/agent-files/assistant/notes.txt
```

**Use when:**

* Agent accesses shared configuration or templates
* All users see the same reference files
* Building knowledge base or documentation assistants
* Single-tenant applications

### All

**No isolation** - Files shared across all agents and users:

```python theme={null}
tools=[FilesystemTools(visibility="all")]
```

**Path structure:**

```
/tmp/agent-files/
```

**Use when:**

* Building single-user development tools
* Prototyping and testing
* Files genuinely need to be shared globally

***

## Available Operations

Filesystem tools provide eight operations for file management:

### List Directory

List files and directories:

```python theme={null}
# Agent can call: list_directory(path=".")
# Returns: List of files and directories with metadata
```

### Read File

Read file contents:

```python theme={null}
# Agent can call: read_file(path="notes.txt")
# Agent can call: read_file(path="log.txt", start_line=10, end_line=20)
# Returns: File contents as text
```

### Write File

Create or overwrite files:

```python theme={null}
# Agent can call: write_file(path="report.txt", content="...")
# Creates: report.txt with specified content
```

### Edit File

Modify existing files with search/replace:

```python theme={null}
# Agent can call: edit_file(
#   path="config.json",
#   old_string="\"debug\": false",
#   new_string="\"debug\": true"
# )
```

### Find Files

Search for files by name pattern:

```python theme={null}
# Agent can call: find_files(pattern="*.txt")
# Agent can call: find_files(pattern="**/*.md")
# Returns: List of matching file paths
```

### Search in Files

Search file contents with regex:

```python theme={null}
# Agent can call: search_in_files(pattern="TODO", path=".")
# Agent can call: search_in_files(pattern="def main", path=".", context_lines=2)
# Returns: Files containing the search term with context
```

### Remove File

Delete a file:

```python theme={null}
# Agent can call: remove_file(path="temp.txt")
```

### Remove Directory

Delete a directory:

```python theme={null}
# Agent can call: remove_directory(path="temp")
# Agent can call: remove_directory(path="old_project", recursive=True)
```

***

## Factory Mode vs Direct Mode

### Factory Mode (Recommended)

In factory mode, pass `FilesystemTools()` to the agent. The framework automatically creates the right instance with proper isolation:

````python theme={null}
```python images/main/main.py
from autonomy import Agent, FilesystemTools, Model, Node


async def main(node):
  await Agent.start(
    node=node,
    name="assistant",
    instructions="You are a helpful assistant",
    model=Model("claude-sonnet-4-v1"),
    tools=[FilesystemTools(visibility="conversation")]
  )


Node.start(main)
````

The framework automatically:

1. Extracts `scope` and `conversation` from each request
2. Creates an isolated `FilesystemTools` instance for that context
3. All file operations stay within the visibility boundary

**This is the recommended approach** for multi-user applications.

### Direct Mode

Direct mode specifies the full context upfront:

```python theme={null}
from autonomy import FilesystemTools, Tool

# Create instance with specific context
fs = FilesystemTools(
  visibility="scope",
  agent_name="assistant",
  scope="user-alice",
  base_dir="/data/files"
)

# Use directly
tools = [
  Tool(fs.read_file),
  Tool(fs.write_file),
  Tool(fs.list_directory)
]
```

**Use direct mode when:**

* Building single-user applications
* Running agents outside the HTTP API
* You need explicit control over file paths
* Testing and development

***

## Configuration

### Custom Base Directory

Change where files are stored:

```python theme={null}
tools=[FilesystemTools(
  visibility="conversation",
  base_dir="/data/agent-files"  # Custom location
)]
```

### Multiple Filesystem Instances

Provide different filesystem access with different visibility levels:

```python theme={null}
from autonomy import FilesystemTools

# Shared templates (all users can read)
templates_fs = FilesystemTools(visibility="agent")

# User-specific workspace
workspace_fs = FilesystemTools(visibility="scope")

await Agent.start(
  node=node,
  name="assistant",
  instructions="""
  You access two filesystems:
  - Shared templates in the agent filesystem
  - Your personal workspace in the scope filesystem
  """,
  model=Model("claude-sonnet-4-v1"),
  tools=[templates_fs, workspace_fs]
)
```

***

## Complete Example

Build a document assistant with user-specific workspaces:

```python images/main/main.py theme={null}
from autonomy import Agent, FilesystemTools, Model, Node


async def main(node):
  await Agent.start(
    node=node,
    name="document_assistant",
    instructions="""
    You are a document assistant that helps users manage their files.
    
    Capabilities:
    - List files in their workspace
    - Read and write documents
    - Search for content across files
    - Organize files into directories
    
    Each user has their own isolated workspace. Files are persistent
    across conversations for the same user.
    """,
    model=Model("claude-sonnet-4-v1"),
    tools=[FilesystemTools(visibility="scope")]
  )


Node.start(main)
```

```bash images/main/Dockerfile theme={null}
FROM ghcr.io/build-trust/autonomy-python
COPY . .
ENTRYPOINT ["python", "main.py"]
```

```yaml autonomy.yaml theme={null}
name: docu
pods:
  - name: main-pod
    public: true
    containers:
      - name: main
        image: main
```

**Usage examples:**

```bash theme={null}
# User Alice creates a document
curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"message":"Create a file called project-notes.md with my project ideas", "scope":"user-alice"}' \
  "https://CLUSTER-ZONE.cluster.autonomy.computer/agents/document_assistant"

# Later, in a different conversation, Alice can still access it
curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"message":"Read my project-notes.md file", "scope":"user-alice", "conversation":"new-chat"}' \
  "https://CLUSTER-ZONE.cluster.autonomy.computer/agents/document_assistant"

# User Bob has a completely separate workspace
curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"message":"List my files", "scope":"user-bob"}' \
  "https://CLUSTER-ZONE.cluster.autonomy.computer/agents/document_assistant"
```