AI Agent

How to Connect AI Agents to Local Files

July 02, 2026 · 4 min read · YayaAgent Team

Most people picture local file access as a single on/off switch — either your agent can touch your drive, or it can't. That's not how it works. It's a layered permission system: what directory the agent can see, which operations it can perform inside that directory, and whether it's allowed to leave that directory at all. Get those three layers right and file access is one of the safest things you can hand an agent.

This guide covers exactly that: how to connect your agents to the local file system, securely and practically.

Before diving in, two things worth having under your belt:

Already have an agent installed? This guide assumes you're working with OpenClaw or Hermes. If not, start with the OpenClaw installation guide or the Hermes setup guide.
New to agent architecture? It helps to understand what tools actually are before modifying configuration files. Tools are the typed functions that bridge the gap between LLM reasoning and your local machine.

Quick Decision Guide

Scenario	Recommended Approach
Lightweight agents on a dedicated VPS (max I/O speed)	Direct host config, no sandbox
Testing unverified third-party frameworks	Docker sandbox mode, restricted `group:fs`
Production or sensitive data	Strict workspace isolation + explicit allow-lists

1. Connecting OpenClaw to Local Files

OpenClaw doesn't use a separate fs_read/fs_write config block. File access is one of five built-in tool groups (group:fs, group:runtime, group:ui, group:messaging, plus individually named tools), and you control it through the same openclaw.json file that governs the rest of the agent.

If you haven't installed OpenClaw yet:

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

(Windows users run the PowerShell installer from the OpenClaw site instead of the curl command.)

The setup wizard creates ~/.openclaw/openclaw.json and a default workspace at ~/.openclaw/workspace. To scope file access for a specific agent, edit that file directly (it's JSON5 — comments and trailing commas are fine):

// ~/.openclaw/openclaw.json
{
  agents: {
    list: [
      {
        id: "local-dev-agent",
        workspace: "/path/to/your/project",
        sandbox: {
          mode: "session",       // isolates each session in its own container
          workspaceAccess: "rw", // read+write, but only inside the workspace path
        },
        tools: {
          allow: ["group:fs"],   // read, write, edit, apply_patch
          deny: ["exec", "process"],
        },
      },
    ],
  },
}

group:fs bundles the four file-operation tools (read, write, edit, apply_patch). If you want read-only access, allow only "read" instead of the whole group. workspace is the hard boundary — the agent's file tools can't reach outside it regardless of what you put in allow.

After editing, validate before restarting:

openclaw config validate

Most config changes hot-apply without a restart; if something doesn't take effect, run openclaw doctor --fix to check for a rejected or invalid config write.

2. Connecting Hermes to Local Files

Hermes doesn't have an installable "local file system skill" — file access is a built-in toolset (the File Operations toolset), and what directory it can reach depends on how you're running Hermes, not on which skill you enabled.

If you haven't installed Hermes yet:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup --portal

Local / Bare-Metal Deployments

By default Hermes reads and writes wherever it's launched from, scoped to the File Operations toolset. Confirm the toolset is enabled and adjust it interactively:

hermes tools

This opens a picker for enabling/disabling File Operations, Terminal, Browser, and other toolsets — there's no config flag to hand-edit for this.

Docker Deployments (Recommended for isolation)

Hermes itself needs a persistent volume for its own state (config.yaml, .env, sessions, memory, skills). Your project directory is mounted separately as the workspace the agent will actually read and write:

services:
  hermes-agent:
    image: nousresearch/hermes-agent:latest
    volumes:
      - hermes_home:/root/.hermes        # Hermes' own config/memory/skills — do not skip this
      - ./local-workspace:/workspace      # the directory you want the agent to access
    environment:
      - OPENAI_API_KEY=your_key_here

volumes:
  hermes_home:

For extra isolation on top of that — sandboxing shell commands the agent runs, separate from which files it can see — set the terminal backend to Docker as well:

hermes config set terminal.backend docker

Run hermes doctor after any config change; it catches provider, permission, and mount issues before you find them mid-session.

3. Security and Sandboxing: Myth vs. Reality

Myth: Giving an AI agent access to your file system is inherently dangerous and will inevitably lead to corrupted data.

Reality: File access is highly secure when you enforce a hard workspace boundary and grant only the operations the agent actually needs. Think of it as the difference between handing someone the master key to your entire building versus a keycard that opens exactly one filing cabinet.

A few rules of thumb:

Default to read-only (allow "read", not the full group:fs) unless the agent genuinely needs to write output.
Set workspace (OpenClaw) or the mounted volume path (Hermes) to the narrowest directory that still lets the agent do its job.
Run agents in a sandboxed session or Docker container whenever possible — it isolates command execution, not just file access.
Audit tools.allow/deny and mounted paths regularly, and check logs for anomalies.

Troubleshooting

Symptom	Fix
Agent can't write files even though `group:fs` is allowed	Check `sandbox.workspaceAccess` — it may be set to `"none"` or `"read"`, which overrides the tool allow-list
Config changes not applying (OpenClaw)	Run `openclaw config validate`, then `openclaw doctor --fix` if invalid
File Operations toolset missing (Hermes)	Run `hermes tools` and confirm it's enabled — a "Blank Slate" install disables everything except providers, File Operations, and Terminal
Files not persisting after container restart (Hermes)	Confirm `hermes_home` is a named volume, not an anonymous one — anonymous volumes don't survive `docker compose up -d --force-recreate`

Bottom Line

Local file access isn't one setting — it's the combination of a workspace boundary, a tool allow-list, and (optionally) a sandbox layer around command execution. OpenClaw expresses this through openclaw.json's workspace + tools.allow + sandbox fields; Hermes expresses it through the File Operations toolset plus whatever directory you mount or launch it from. Get the boundary right first, then loosen the tool permissions only as far as the task actually needs.

Once that's working, the natural next step is giving your agent web access — combining local file manipulation with live internet lookups lets it fetch up-to-date documentation and write back to your codebase in one pass.