Intermediate 📅 Last Updated: July 1, 2026 ⏱️ 12 min read 🤖 Local AI Agents

How to Give an AI Agent Access to Your Project Files Safely

Who This Is For

Read this if: You are running a local agent (Goose, Aider, OpenHands, Continue) and it needs to read or edit real project files. You want to keep your dotfiles, secrets, and unrelated projects safe.

Skip if: You are only chatting with a model through Open WebUI or Ollama CLI — no file access involved. Nothing here applies yet.

What You Need

• An agent installed — this guide uses Goose and Aider as examples (see Goose guides)
• A project folder under git — so every agent edit is reversible with git checkout
• 5 minutes to set permission levels before the first run

The 4 Permission Levels

Think of file access as four escalating trust tiers. Always start at the lowest level that gets the job done.

Step-by-Step: Locking Down Goose

Step 1: Put Your Project Under Git

This is your safety net. Every agent edit becomes a diff you can reject.

cd ~/projects/my-app
git init
git add -A
git commit -m "baseline before agent work"

Step 2: Start in Read-Only Mode

Point Goose at the project folder with no write access:

# Goose: restrict to one directory, read-only
goose session --path ~/projects/my-app --permissions read

# Aider: read-only by default, must opt into edits
aider --no-auto-commits --subtree-only ./src

Now ask the agent to review the code. It can read everything in my-app but cannot change a single byte. If it suggests an edit, apply it yourself.

Step 3: Escalate to Read-Write When Ready

# Goose: allow edits inside the project only
goose session --path ~/projects/my-app --permissions read write

The agent still cannot touch ~/.ssh, ~/.config, your browser profile, or any other project. Commit after each task so you can roll back:

# Review what the agent changed
git diff

# Keep it
git add -A && git commit -m "agent: refactor auth module"

# Reject it
git checkout .

Step 4 (Advanced): Shell Access in a Sandbox

Only do this inside a container. The agent can run commands but cannot escape.

# Run the agent inside a Docker sandbox with a mounted volume
docker run -it --rm \
  -v ~/projects/my-app:/workspace \
  -w /workspace \
  --network none \
  sandbox-agent:latest

# Inside the sandbox, the agent sees /workspace only.
# No home directory. No SSH keys. No internet.

What to Allow vs Block — The Checklist

Common Mistakes & Errors

Mistake 1: Running the Agent From ~/

Cause: You launch the agent in your home directory "for convenience," so it sees every file you own — including .env files with API keys.

Fix: Always cd into the specific project before launching. Use --subtree-only or the equivalent flag so the agent cannot walk up the tree.

Mistake 2: Granting Shell Access Without a Sandbox

Cause: An agent with shell permission can run rm -rf, curl secrets to a remote server, or install malware. A prompt-jailbreak can trigger all of this.

Fix: Never give Level 3 access on your host OS. Use Docker, Firejail, or a VM. See the warning below.

Mistake 3: Not Committing Before Agent Work

Cause: The agent rewrites 40 files. You liked the old versions. They are gone.

Fix: git commit before every agent session. git checkout . is your undo button.

Mistake 4: Trusting "Auto-Approve" Modes

Cause: Some agents have a YOLO/auto-approve setting that skips confirmation. Convenient, dangerous.

Fix: Leave it off. Approve edits manually until you trust a specific workflow, then re-enable only inside a sandbox.

Recommended Setup (Tiered)

What I Would Do

Default to read-only, scoped to the project folder. Move to read-write only when the agent has proven it understands the codebase, and always commit first so git checkout . undoes a bad edit. I have never given an agent shell access on my host OS. The one time I needed it for running tests, I spun up a throwaway container with --network none. Two minutes of setup saves you from a wiped home directory.

Frequently Asked Questions

How do I safely give an AI agent access to my files?

Run the agent in Docker with specific directories mounted as read-only volumes. This limits access to only files you share and prevents modification. Tools like Goose have built-in permission systems that ask approval before file operations.

What is the most common security mistake with local AI agents?

Giving unrestricted read-write access to your entire home directory. This can lead to accidental deletion, exposure of SSH keys or .env files, or harmful commands. Always scope access to the minimum directory needed.

Should I give an agent read-only or read-write access?

Start with read-only for most research and analysis tasks. Grant write access only to a specific output directory. Tools like Goose let you set per-directory permissions to mix read-only and write-access paths.

Does Docker isolation protect against all risks?

Docker significantly reduces risk by containing file access, network calls, and system changes. However, it does not prevent data exfiltration over network if the agent has internet access. Combine Docker with network restrictions for maximum safety.

How do I manage permissions for an agent like Goose?

Goose has a permission system prompting approval for each tool action. Configure allowlists in the config file to pre-approve specific directories or commands. Use '--no-auto-approve' for sensitive environments.

Last Updated: July 1, 2026 — Verified against Goose 1.0 and Aider 0.7 on Ubuntu 26.04 LTS.