> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synti.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Filesystem Sources

> Bookmark folders on your machine so Synti's agent can read and reference them across conversations.

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](/core-concepts/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](/sources/overview) for how all three source kinds compare.

## Adding a folder

You can add a folder two ways:

<Steps>
  <Step title="Ask the agent">
    Say "add my \~/Notes folder as a source." Synti creates the configuration and validates the path for you.
  </Step>

  <Step title="Create it by hand">
    Add a folder under your workspace's sources directory with a `config.json`:

    ```json config.json theme={null}
    {
      "type": "local",
      "name": "Notes",
      "slug": "notes",
      "enabled": true,
      "provider": "local",
      "local": {
        "path": "/Users/you/Notes"
      }
    }
    ```
  </Step>
</Steps>

| Field        | Purpose                                       |
| ------------ | --------------------------------------------- |
| `type`       | Must be `"local"`                             |
| `name`       | Display name in the sources list              |
| `slug`       | URL-safe identifier (matches the folder name) |
| `enabled`    | Whether the source is active                  |
| `provider`   | Set to `"local"`                              |
| `local.path` | Absolute path to the directory on disk        |

<Tip>
  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.
</Tip>

## 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](/core-concepts/permissions) prompts before it runs.

<Warning>
  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.
</Warning>

## 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.