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

# File System

> Read, write, list, and inspect local files with path sandboxing.

# File System

Read, write, list, and inspect local files. All paths are sandboxed to a `basePath` directory, preventing traversal attacks.

***

## Quick Start

```typescript theme={null}
import { Agent, openai, FileSystemToolkit } from "@agentium/core";

const fsTk = new FileSystemToolkit({
  basePath: "./data",
  allowWrite: true,
});

const agent = new Agent({
  name: "file-manager",
  model: openai("gpt-4o"),
  instructions: "Help manage files in the data directory.",
  tools: [...fsTk.getTools()],
});

const result = await agent.run("List all files in the data directory");
```

***

## Config

<ParamField body="basePath" type="string">
  Root directory for file access. All paths are resolved relative to this. Prevents directory traversal.
</ParamField>

<ParamField body="allowWrite" type="boolean" default="false">
  Enable the `fs_write_file` tool. Disabled by default for safety.
</ParamField>

***

## Tools

| Tool                | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| `fs_read_file`      | Read the contents of a file.                                       |
| `fs_list_directory` | List files and subdirectories. Supports recursive listing.         |
| `fs_file_info`      | Get file metadata (size, type, modified/created dates).            |
| `fs_write_file`     | Write or append to a file. Only available when `allowWrite: true`. |

<Warning>
  Enable `allowWrite` only when necessary. Always set a `basePath` to restrict file access.
</Warning>