Local Folders

Bookmark folders on your machine as sources — Obsidian vaults, code repos, data directories. How the allowlist model works and what tools the agent gets.

Local sources bookmark a folder on your machine so the agent can work inside it without needing to know its full path each time. Common uses: your Obsidian vault, a code repository, a directory of exported data, your dotfiles.

Unlike MCP and API sources, a local source doesn't talk to a remote service. It points at a path, and the agent uses regular shell and file tools scoped to that path.

Adding a local folder

Either tell the agent:

"Add my Obsidian vault at ~/Documents/vault as a source."

or use the Sources UI → Add Source → Local, and pick the folder.

Config schema

{
  "id": "obsidian_v1a2b3",
  "name": "Obsidian vault",
  "slug": "obsidian",
  "provider": "filesystem",
  "type": "local",
  "icon": "📓",
  "tagline": "Personal notes and daily journals",
  "enabled": true,
  "local": {
    "path": "~/Documents/vault",
    "format": "obsidian"
  }
}

Fields inside local:

Field	Type	Purpose
`path`	string, required	Absolute or `~`-rooted path. Shell vars like `$HOME` are expanded on load.
`format`	string, optional	Hint for the agent about what's in the folder — `filesystem`, `obsidian`, `git`, `sqlite`, or custom. Used to tailor `guide.md`.

Paths are stored portably — Fabric Agents converts /Users/you/vault to ~/vault (or equivalent) so you can sync your workspace across machines without rewriting the config.

What the agent gets

Enabling a local source doesn't add a new tool type. The agent already has file and shell tools (Read, Write, Edit, Bash, Grep, Glob) that can operate anywhere. The local source does two things:

Writes a guide.md describing the folder's contents, structure, and conventions. This is what the agent reads at the start of a session to know what lives where — your vault's tag scheme, your repo's module layout, which files are generated, and so on.
Applies permissions from the source's permissions.json when the session is in Explore (safe) mode. In Ask and Execute modes, the session's global mode-level policy applies.

If you enable a local source and never mention it, you're not losing anything — the agent still has its usual tools. The source mainly pays off when the agent wants to orient itself: instead of grepping blindly, it reads guide.md first.

The allowlist

permissions.json scopes what the agent can do in Explore mode. For local sources the main field is allowedBashPatterns:

{
  "allowedBashPatterns": [
    { "pattern": "^ls\\s", "comment": "List files" },
    { "pattern": "^cat\\s", "comment": "Read file contents" },
    { "pattern": "^grep\\s", "comment": "Search" },
    { "pattern": "^rg\\s", "comment": "ripgrep" },
    { "pattern": "^git\\s(log|status|diff|blame|show)" }
  ]
}

Each entry is a regex matched against the full command line. Reads are typically allowed; writes (mv, rm, >, >>) stay off unless you add them. Read, Grep, and Glob are already read-only, so they work in Explore mode without explicit entries.

Format hints

The format field steers what guide.md highlights. Common values:

`format`	What the agent looks for
`filesystem`	Generic directory.
`obsidian`	Vault layout — daily notes, tags, backlinks, `.obsidian/` config.
`git`	Recent commits, branches, `.gitignore`, README.
`sqlite`	Schema, table row counts.
Custom	Whatever the agent learns when writing the guide.

You can change the hint any time; edit config.json and re-ask the agent to regenerate guide.md.

Multi-folder setups

Each local source is one path. If you work across several repos or vaults, add one source per folder. The agent can use several at once:

@my-dotfiles @work-repo Fix the bash alias in dotfiles to match the new build script name in work-repo.

Edge cases

Symlinks — Shell and file tools follow symlinks based on the OS's native behaviour. Fabric Agents doesn't add a symlink sandbox. If a folder under your source contains a symlink to /etc, shell patterns that allow cat will happily read /etc/passwd through the link. Keep allowlists tight if you don't trust the folder's contents.

Path traversal — There's no hard jail around the source folder. Allowlists are command-pattern matchers, not path matchers. If you let the agent run cat generally, cat ../other/file works. Scope patterns narrowly (e.g., include explicit paths), use read-only commands, or keep the source behind Ask-to-Edit mode where prompts catch surprises.

Case sensitivity — On macOS (case-insensitive file systems) the agent may access Readme.md when you wrote allowlists against README.md. Patterns are applied to the command string as-typed, not the normalised filename.

Sources overview — how sources are scoped per-workspace.
Permissions — how Explore / Ask / Execute modes interact with allowlists.
Workspaces — you can also make the entire workspace root a working directory without creating a local source.

On this page