Skip to main content
A local filesystem source is a bookmark to a directory on your machine. Once you add one, Synti’s agent can browse and read its contents whenever a task calls for it—your notes vault, a downloads folder, a library of reference documents. Because Synti runs locally, nothing about the folder leaves your computer; the source simply tells the agent where to look.

​
When to use a filesystem source

Filesystem sources shine when you keep returning to the same folders—reference material, an archive, a knowledge base you consult often. They differ from the Working Directory, which is the single project the agent is actively building in with full tooling. Use a Working Directory for the project at hand; use filesystem sources to bookmark the other places you want the agent to reach. See Sources for how all three source kinds compare.

​
Adding a folder

You can add a folder two ways:
1

Ask the agent

Say “add my ~/Notes folder as a source.” Synti creates the configuration and validates the path for you.
2

Create it by hand

Add a folder under your workspace’s sources directory with a config.json:
config.json
Add a local.format hint for structured vaults—for example "obsidian"—so the agent understands the folder’s conventions, such as wiki-links and note layout.

​
What the agent can do

By default a filesystem source is read-oriented. The agent explores it with the Read, Glob, and Grep tools and with common shell commands like ls, cat, head, tail, and grep. That’s enough to search notes, pull quotes, and summarize documents without touching anything. Write tools exist, but they are not granted by default. A filesystem source starts in read-only Explore mode so the agent can look but not modify. To allow writes or specific commands, broaden the source’s permissions.

​
Permissions

To customize what commands a folder permits, add a permissions.json next to config.json with allowedBashPatterns listing the commands you want to authorize. The patterns are scoped to this source only, so loosening one folder never affects another. Anything beyond the allowed set still routes through Synti’s Permissions prompts before it runs.
Granting write or broad shell access to a folder lets the agent change files there. Only widen permissions on directories you’re comfortable having the agent modify, and keep sensitive folders read-only.

​
Documenting a folder

Drop a guide.md inside the source folder to tell the agent what the directory contains, how it’s organized, and any conventions to follow. A short guide—“this is my research archive, one Markdown file per paper, cite by filename”—noticeably improves how well the agent navigates the folder.