# How aisuite's Built-In Toolkits (files, git, shell) Provide Sandboxed Functionality

> Learn how aisuite's built-in toolkits provide sandboxed functionality. Explore restricted file access, read-only git checks, and whitelisted shell commands for secure execution.

- Repository: [Andrew Ng/aisuite](https://github.com/andrewyng/aisuite)
- Tags: internals
- Published: 2026-08-03

---

**aisuite's built-in toolkits enforce sandboxed execution by confining file operations to approved root directories, restricting git commands to read-only status checks, and limiting shell execution to explicitly whitelisted commands while blocking dangerous operators like pipes and redirections.**

The andrewyng/aisuite repository provides LLM agents with safe access to host environments through three core toolkits that implement defense-in-depth sandboxing. By combining path validation, capability gating, and command filtering, these toolkits prevent agents from escaping their designated boundaries while still enabling productive file manipulation, version control inspection, and shell command execution.

## How the Files Toolkit Enforces Filesystem Sandboxing

The **Files toolkit** restricts all filesystem operations to one or more designated root directories, ensuring agents cannot access sensitive system paths outside their sandbox.

**Root Directory Confinement**

Every path operation routes through `FileToolkit._resolve_path`, which validates that the resolved path remains a child of an allowed root. If path traversal attempts to escape the sandbox, the method raises a `PermissionError` immediately【#85-L91】.

**Write Capability Gating**

Write operations are disabled by default. The toolkit only exposes write capabilities when a root is explicitly marked as writable via the `allow_write` parameter or when the root entry itself has write permissions configured. This prevents accidental or malicious file modifications.

**Default Ignore Patterns**

The toolkit uses `DEFAULT_IGNORES` to automatically exclude common sensitive directories such as `.git`, `.venv`, and `node_modules` from file listings and searches, reducing the attack surface.

```python
from aisuite.toolkits import files

# Initialize with read-only access confined to /home/user/project

fs_tools = files(root="/home/user/project", allow_write=False)

# list files (low risk)

list_files = fs_tools[0]  # tool wrapper

print(list_files(path="src", pattern="*.py"))

# read a file (low risk)

read_file = fs_tools[1]
print(read_file(path="README.md"))

```

## How the Git Toolkit Restricts Repository Access

The **Git toolkit** provides read-only access to repository information, preventing agents from modifying version control history or pushing unauthorized changes.

**Read-Only Operations**

The toolkit exposes only non-mutating utilities such as `git status` and `git diff`. It never performs write operations, ensuring repository integrity.

**Path Traversal Prevention**

Similar to the Files toolkit, `GitToolkit._resolve_path` validates that all paths remain within the configured repository root, preventing attempts to access files outside the sandbox【#85-L91】.

**Output Limiting**

To prevent log flooding or information leakage, the toolkit clips command output to `max_output_chars`, ensuring manageable response sizes.

```python
from aisuite.toolkits import git

# Initialize git toolkit bound to specific repository

git_tools = git(root="/home/user/project")
status = git_tools[0]  # git_status tool

print(status())

```

## How the Shell Toolkit Controls Command Execution

The **Shell toolkit** executes commands within a configured working directory while strictly controlling which commands can run and how they can be constructed.

**Whitelist Enforcement**

`ShellToolkit.__init__` requires either an explicit `allowed_commands` list or the `allow_all=True` flag【#64-L68】. By default, only exact matches from the whitelist are permitted, preventing execution of arbitrary system binaries.

**Shell Syntax Filtering**

Unless `allow_shell=True` is explicitly set, the `_validate_command` method checks the whitelist and invokes `_validate_no_shell_syntax` to reject any command containing pipes, redirections, or other shell operators【#13-L21】【#23-L30】. The `UNSUPPORTED_SHELL_TOKENS` enumeration defines these disallowed tokens explicitly【#11-L12】.

**Execution Context**

Commands execute only within the configured `cwd` (current working directory), and output is truncated to `max_output_chars`. When a run context exists, large outputs can be stored as artifacts rather than returned directly.

```python
from aisuite.toolkits import shell

# Strict shell with whitelisted commands only

shell_tools = shell(
    cwd="/home/user/project",
    allowed_commands=["ls", "git status"],
    allow_all=False,
    allow_shell=False,
)

run_cmd = shell_tools[0]  # run_shell tool

print(run_cmd("ls -la"))          # ✅ allowed

# print(run_cmd("rm -rf *"))      # ❌ raises PermissionError

```

## Summary

- **Filesystem sandboxing** confines all file operations to designated root directories, with `FileToolkit._resolve_path` enforcing path boundaries and write capabilities requiring explicit opt-in.
- **Git sandboxing** restricts agents to read-only commands (`git status`, `git diff`) with path validation preventing repository traversal, ensuring version control integrity.
- **Shell sandboxing** combines command whitelisting, working directory restriction, and shell syntax filtering via `UNSUPPORTED_SHELL_TOKENS` to prevent arbitrary code execution and command injection.

## Frequently Asked Questions

### What happens if an LLM agent tries to access a file outside the allowed root directories?

The `FileToolkit._resolve_path` method raises a `PermissionError` immediately when it detects a path resolution attempt that would traverse outside the configured root directories【#85-L91】. This prevents directory traversal attacks and ensures agents remain within their designated filesystem boundaries.

### Can the git toolkit modify repository history or push changes?

No, the git toolkit intentionally provides only read-only utilities. It exposes functions like `git status` and `git diff` but never performs mutating commands such as `git commit`, `git push`, or `git reset`. This design ensures that agents can inspect repository state without risking modifications to version control history.

### How does the shell toolkit prevent command injection attacks?

The shell toolkit employs multiple layers of defense. First, `ShellToolkit.__init__` requires either an explicit `allowed_commands` whitelist or `allow_all=True`【#64-L68】. Second, unless `allow_shell=True` is set, the `_validate_no_shell_syntax` method blocks commands containing pipes, redirections, or other operators defined in `UNSUPPORTED_SHELL_TOKENS`【#11-L12】【#23-L30】, preventing shell injection and command chaining.

### Is write access enabled by default in the files toolkit?

No, write access is disabled by default. The toolkit only permits write operations when a root directory is explicitly configured as writable through the `allow_write` parameter or when the specific root entry has write permissions enabled. This default-deny approach ensures agents cannot modify files unless explicitly authorized.