llm4s-docs/org.llm4s/org.llm4s.toolapi/org.llm4s.toolapi.builtin/org.llm4s.toolapi.builtin.filesystem

org.llm4s.toolapi.builtin.filesystem

package org.llm4s.toolapi.builtin.filesystem

File system tools for reading, writing, and managing files.

These tools provide safe access to the file system with configurable path restrictions and size limits.

== Configuration ==

All file system tools accept FileConfig for read operations or WriteConfig for write operations. These configurations allow:

Path allowlists and blocklists for security
File size limits
Symbolic link handling

== Available Tools ==

ReadFileTool: Read file contents
WriteFileTool: Write content to files (requires explicit path allowlist)
ListDirectoryTool: List directory contents
FileInfoTool: Get file metadata

Attributes

Example

import org.llm4s.toolapi.builtin.filesystem._
import org.llm4s.toolapi.ToolRegistry
// Read-only tools with default config (blocked: /etc, /var, /sys, /proc, /dev)
for {
 readFile <- ReadFileTool.toolSafe
 listDir  <- ListDirectoryTool.toolSafe
 fileInfo <- FileInfoTool.toolSafe
} yield new ToolRegistry(Seq(readFile, listDir, fileInfo))
// Or use the convenience val
readOnlyToolsSafe.map(tools => new ToolRegistry(tools))
// Tools with custom restrictions
val config = FileConfig(
 maxFileSize = 512 * 1024,
 allowedPaths = Some(Seq("/tmp", "/home/user/workspace"))
)
for {
 readFile <- ReadFileTool.createSafe(config)
 listDir  <- ListDirectoryTool.createSafe(config)
} yield new ToolRegistry(Seq(readFile, listDir))
// Write tool with explicit allowlist
val writeConfig = WriteConfig(
 allowedPaths = Seq("/tmp/output"),
 allowOverwrite = true
)
for {
 writeTool <- WriteFileTool.createSafe(writeConfig)
} yield new ToolRegistry(Seq(writeTool))

Members list

Type members

Classlikes

Configuration for file system tools.

== How a path is judged == By where it really is, not by how it is spelled: every symbolic link is replaced by its real target, then the result is compared with each entry, resolved the same way, one path component at a time. isPathAllowed judges the path as given, and a .. after a link is read both ways an OS reads it: physically, as POSIX does (link/.. is the parent of the link's target), and lexically, as Windows does (.. removed as text before links are followed, so link/.. is the directory holding the link). The path is allowed only when both locations are allowed, whatever platform the check runs on; a path whose readings disagree, one inside and one outside, is refused on every OS. The tools first remove . and .. from the path they are given as text (data/link/../x is data/x for them), so the two readings agree, and then judge and open that location, so what they open is what they checked. /srv/data allows /srv/data/x and does not allow /srv/data-secret/x. A symbolic link that cannot be resolved (a dangling link) is refused. The tools open the resolved path, so a link swapped in after the check does not redirect the open; a directory swapped for a link between the resolution and the open is a race this narrows and does not close. A hard link is not contained: a hard link inside an allowed directory to a file elsewhere is that file under an allowed name, and no path check can tell it apart, so do not let untrusted parties create files in an allowed directory.

Value parameters

allowedPaths: Paths that are allowed to be accessed. None means any path. An entry that is itself reached through a symbolic link (such as /tmp on macOS) is resolved, and so are the paths checked against it.
blockedPaths: Paths that are blocked from access (takes precedence over allowedPaths). Matched on the real location too, so blocking /etc also blocks /private/etc on macOS, and the default /var also blocks /private/var, where macOS keeps per-user temporary directories.
followSymlinks: Whether to follow a symbolic link that is the final component of the path (default: false for security). When false, read_file reports such a link as not a regular file and file_info and list_directory describe the link itself. This does not decide whether a link may lead out of the allowed area: a link anywhere on the path, final or not, is resolved first, and the path is allowed only if its real location is.
maxFileSize: Maximum file size to read in bytes (default: 1MB)

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Information about a single file or directory entry.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: FileEntry.type

Detailed information about a file.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: FileInfoResult.type

Tool for getting detailed file information.

Features:

File metadata (size, timestamps)
File type detection
Permission checks
Human-readable size formatting

Attributes

Example

import org.llm4s.toolapi.builtin.filesystem._
val infoTool = FileInfoTool.create(FileConfig(
 allowedPaths = Some(Seq("/tmp"))
))
val tools = new ToolRegistry(Seq(infoTool))
agent.run("Get info about /tmp/data.txt", tools)

Supertypes

class Object

trait Matchable

class Any

Self type

FileInfoTool.type

Result from listing a directory.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: ListDirectoryResult.type

Tool for listing directory contents.

Features:

List files and directories
File metadata (size, modified time)
Configurable max entries
Path restrictions

Attributes

Example

import org.llm4s.toolapi.builtin.filesystem._
val listTool = ListDirectoryTool.create(FileConfig(
 allowedPaths = Some(Seq("/tmp", "/home/user"))
))
val tools = new ToolRegistry(Seq(listTool))
agent.run("List files in /tmp", tools)

Supertypes

class Object

trait Matchable

class Any

Self type

ListDirectoryTool.type

Result from reading a file.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: ReadFileResult.type

Tool for reading file contents.

Features:

Configurable size limits
Path restrictions for security
Optional line limit
Encoding detection

Attributes

Example

import org.llm4s.toolapi.builtin.filesystem._
val readTool = ReadFileTool.create(FileConfig(
 maxFileSize = 512 * 1024,
 allowedPaths = Some(Seq("/tmp", "/home/user/workspace"))
))
val tools = new ToolRegistry(Seq(readTool))
agent.run("Read the contents of /tmp/data.txt", tools)

Supertypes

class Object

trait Matchable

class Any

Self type

ReadFileTool.type

Configuration for write operations.

A path is judged by where it really is, as for FileConfig: symbolic links are resolved (for a file that does not exist yet, the nearest existing ancestor is), with a .. after a link read both the POSIX and the Windows way and both locations required to be allowed, then compared with each allowed entry one component at a time. A link inside an allowed directory that leads outside it is therefore refused, whether the link is a directory on the way to the file or the file itself; a link that leads to another place inside the allowed directory is written through. The tool writes to the resolved path.

Value parameters

allowOverwrite: Whether to allow overwriting existing files
allowedPaths: Paths where writing is allowed (required for safety)
createDirectories: Whether to create parent directories if they don't exist
maxFileSize: Maximum file size to write in bytes

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Result from writing a file.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: WriteFileResult.type

Tool for writing file contents.

IMPORTANT: This tool requires explicit path allowlisting for safety. It will not write to any path that is not in the allowedPaths list.

Features:

Requires explicit path allowlist
Optional append mode
Auto-creates parent directories
Size limits

Attributes

Example

import org.llm4s.toolapi.builtin.filesystem._
val writeTool = WriteFileTool.create(WriteConfig(
 allowedPaths = Seq("/tmp", "/home/user/output")
))
val tools = new ToolRegistry(Seq(writeTool))
agent.run("Write 'Hello World' to /tmp/output.txt", tools)

Supertypes

class Object

trait Matchable

class Any

Self type

WriteFileTool.type

Value members

Concrete fields

All file system tools with default configuration (read-only, excludes write), returning a Result for safe error handling.

Attributes

In this article

Generated with