From 2059e0867f45b029f6078610f707e378d1d00881 Mon Sep 17 00:00:00 2001
From: Juan Antonio Osorio <ozz@stacklok.com>
Date: Mon, 8 Sep 2025 11:26:43 +0300
Subject: [PATCH 1/2] docs: add .thvignore documentation for hiding sensitive
 files

- Add new documentation page explaining .thvignore functionality
- Document how to prevent secrets from leaking into MCP containers
- Include examples for creating and using .thvignore files
- Add reference to .thvignore in run-mcp-servers guide
- Update sidebar to include new .thvignore page under Security section
---
 docs/toolhive/guides-cli/run-mcp-servers.mdx |   4 +-
 docs/toolhive/guides-cli/thvignore.md        | 124 +++++++++++++++++++
 sidebars.ts                                  |   1 +
 3 files changed, 128 insertions(+), 1 deletion(-)
 create mode 100644 docs/toolhive/guides-cli/thvignore.md

diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx
index f0b24304..93f02dca 100644
--- a/docs/toolhive/guides-cli/run-mcp-servers.mdx
+++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx
@@ -118,7 +118,9 @@ To enable file system access for an MCP server, you can either use the
 `--volume` flag to mount specific paths or create a custom permission profile
 that defines read and write permissions.
 
-See [File system access](./filesystem-access.md) for detailed examples.
+See [File system access](./filesystem-access.md) for detailed examples. To
+prevent sensitive files from being exposed when mounting a project, use
+[.thvignore](./thvignore.md).
 
 ### Restrict network access
 
diff --git a/docs/toolhive/guides-cli/thvignore.md b/docs/toolhive/guides-cli/thvignore.md
new file mode 100644
index 00000000..cc5b5d79
--- /dev/null
+++ b/docs/toolhive/guides-cli/thvignore.md
@@ -0,0 +1,124 @@
+---
+title: Hide sensitive files with .thvignore
+description:
+  Use .thvignore to prevent secrets from leaking into MCP containers while
+  keeping fast bind mounts for development.
+---
+
+Some MCP servers need access to your project files, but you don't want to expose
+secrets like `.env`, SSH keys, or cloud credentials. ToolHive supports a
+`.thvignore` mechanism that masks selected paths from the container while
+keeping all other files available through a live bind mount for a smooth
+developer experience.
+
+## How it works
+
+When you mount a directory and a `.thvignore` file is present at the mount
+source, ToolHive resolves the ignore patterns and overlays those paths inside
+the container:
+
+- Directories (for example, `.ssh/`, `node_modules/`): overlaid using a tmpfs
+  mount at the container path
+- Files (for example, `.env`, `secrets.json`): overlaid using a bind mount of a
+  shared, empty host file at the container path
+
+The rest of the files remain bind-mounted from your host, so edits are visible
+in the container immediately.
+
+## Requirements
+
+- ToolHive CLI
+- A mount source directory that contains a `.thvignore` file with patterns to
+  exclude
+
+## Create a .thvignore
+
+Create a `.thvignore` file at the root of the directory you intend to mount. Use
+simple, gitignore-like patterns:
+
+```text
+# secrets
+.env
+.env.*
+*.key
+*.pem
+
+# cloud credentials
+.aws/
+.gcp/
+
+# SSH keys
+.ssh/
+
+# OS junk
+.DS_Store
+```
+
+Guidelines:
+
+- `dir/` matches a directory directly under the mount source
+- `file.ext` matches a file directly under the mount source
+- `*.ext` matches any file with that extension directly under the mount source
+- Lines starting with `#` are comments; blank lines are ignored
+
+## Run a server with .thvignore
+
+Mount your project directory as usual. ToolHive automatically reads `.thvignore`
+if present:
+
+```bash
+thv run --volume ./my-project:/app fetch
+```
+
+To print resolved overlay targets for debugging:
+
+```bash
+thv run --volume ./my-project:/app \
+  --print-resolved-overlays \
+  fetch
+```
+
+The resolved overlays are logged to the workload's log file. For a complete list
+of options, see the [`thv run` command reference](../reference/cli/thv_run.md).
+
+## Global ignore patterns
+
+You can define global ignore patterns at:
+
+```text
+~/.config/toolhive/thvignore
+```
+
+These patterns are loaded in addition to your project's local `.thvignore`.
+
+- Enabled by default
+- Disable for a single run:
+
+```bash
+thv run --ignore-globally=false --volume ./my-project:/app fetch
+```
+
+Recommendation: Store machine-wide patterns (for example, `.aws/`, `.gcp/`,
+`.ssh/`, `*.pem`, `.docker/config.json`) in the global file, and keep
+app-specific patterns (for example, `.env*`, build artifacts) in your project's
+local `.thvignore`.
+
+## Troubleshooting
+
+- Overlays didn't apply
+  - Ensure `.thvignore` exists in the mount source directory (not elsewhere)
+  - Confirm patterns match actual names relative to the mount source
+  - Run with `--print-resolved-overlays` and check the workload's log file path
+    displayed by `thv run`
+
+- Can’t list a parent directory
+  - On SELinux systems, listing a parent directory may fail even though specific
+    files are accessible. Probe individual paths instead (for example, `stat` or
+    `cat`).
+
+## Related information
+
+- [File system access](./filesystem-access.md)
+- [Run MCP servers](./run-mcp-servers.mdx)
+- [Network isolation](./network-isolation.mdx)
+- [`thv run` command reference](../reference/cli/thv_run.md)
diff --git a/sidebars.ts b/sidebars.ts
index 326daf4a..8839f7fc 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -84,6 +84,7 @@ const sidebars: SidebarsConfig = {
           },
           items: [
             'toolhive/guides-cli/filesystem-access',
+            'toolhive/guides-cli/thvignore',
             'toolhive/guides-cli/network-isolation',
           ],
         },

From ac67329f559ee5ba2108cf4a7d806fb5a77f6130 Mon Sep 17 00:00:00 2001
From: Juan Antonio Osorio <ozz@stacklok.com>
Date: Tue, 9 Sep 2025 12:34:07 +0300
Subject: [PATCH 2/2] Address PR feedback for .thvignore documentation

- Fix global config path to be cross-platform compatible (Linux/macOS/Windows)
- Remove redundant Requirements section
- Change section heading to 'Create an ignore file'
- Update file creation description to be more specific
- Replace 'fetch' with 'filesystem' in command examples (better example)
- Update troubleshooting section to use collapsible details format
- Convert recommendation text to use tip admonition format
- Improve global patterns description text
- Add clarification about pattern matching limitations (no full glob syntax)
---
 docs/toolhive/guides-cli/thvignore.md | 80 +++++++++++++++------------
 1 file changed, 46 insertions(+), 34 deletions(-)

diff --git a/docs/toolhive/guides-cli/thvignore.md b/docs/toolhive/guides-cli/thvignore.md
index cc5b5d79..ae481c36 100644
--- a/docs/toolhive/guides-cli/thvignore.md
+++ b/docs/toolhive/guides-cli/thvignore.md
@@ -25,16 +25,10 @@ the container:
 The rest of the files remain bind-mounted from your host, so edits are visible
 in the container immediately.
 
-## Requirements
+## Create an ignore file
 
-- ToolHive CLI
-- A mount source directory that contains a `.thvignore` file with patterns to
-  exclude
-
-## Create a .thvignore
-
-Create a `.thvignore` file at the root of the directory you intend to mount. Use
-simple, gitignore-like patterns:
+Create a file named `.thvignore` at the root of the directory you intend to
+mount. Use simple, gitignore-like patterns:
 
 ```text
 # secrets
@@ -61,21 +55,29 @@ Guidelines:
 - `*.ext` matches any file with that extension directly under the mount source
 - Lines starting with `#` are comments; blank lines are ignored
 
+:::info[Pattern matching]
+
+ToolHive uses simple gitignore-like patterns. Advanced gitignore glob syntax
+like `**/*.env` (to match files in any subdirectory) is not currently supported.
+Patterns only match files and directories directly under the mount source.
+
+:::
+
 ## Run a server with .thvignore
 
 Mount your project directory as usual. ToolHive automatically reads `.thvignore`
 if present:
 
 ```bash
-thv run --volume ./my-project:/app fetch
+thv run --volume ./my-project:/projects filesystem
 ```
 
 To print resolved overlay targets for debugging:
 
 ```bash
-thv run --volume ./my-project:/app \
+thv run --volume ./my-project:/projects \
   --print-resolved-overlays \
-  fetch
+  filesystem
 ```
 
 The resolved overlays are logged to the workload's log file. For a complete list
@@ -83,38 +85,48 @@ of options, see the [`thv run` command reference](../reference/cli/thv_run.md).
 
 ## Global ignore patterns
 
-You can define global ignore patterns at:
-
-```text
-~/.config/toolhive/thvignore
-```
+You can define global ignore patterns in a platform-specific location:
 
-These patterns are loaded in addition to your project's local `.thvignore`.
+- **Linux**: `~/.config/toolhive/thvignore`
+- **macOS**: `~/Library/Application Support/toolhive/thvignore`
+- **Windows**: `%LOCALAPPDATA%\toolhive\thvignore`
 
-- Enabled by default
-- Disable for a single run:
+Patterns contained in the global configuration are loaded in addition to a local
+`.thvignore` file. To disable global patterns for a specific workload, use the
+`--ignore-globally=false` option:
 
 ```bash
-thv run --ignore-globally=false --volume ./my-project:/app fetch
+thv run --ignore-globally=false --volume ./my-project:/projects filesystem
 ```
 
-Recommendation: Store machine-wide patterns (for example, `.aws/`, `.gcp/`,
-`.ssh/`, `*.pem`, `.docker/config.json`) in the global file, and keep
-app-specific patterns (for example, `.env*`, build artifacts) in your project's
-local `.thvignore`.
+:::tip[Recommendation]
+
+Set machine-wide patterns (for example, `.aws/`, `.gcp/`, `.ssh/`, `*.pem`,
+`.docker/config.json`) in the global file, and keep app-specific patterns (for
+example, `.env*`, build artifacts) in your project's local `.thvignore`.
+
+:::
 
 ## Troubleshooting
 
-- Overlays didn't apply
-  - Ensure `.thvignore` exists in the mount source directory (not elsewhere)
-  - Confirm patterns match actual names relative to the mount source
-  - Run with `--print-resolved-overlays` and check the workload's log file path
-    displayed by `thv run`
+<details>
+<summary>Overlays didn't apply</summary>
+
+- Ensure `.thvignore` exists in the mount source directory (not elsewhere)
+- Confirm patterns match actual names relative to the mount source
+- Run with `--print-resolved-overlays` and check the workload's log file path
+  displayed by `thv run`
+
+</details>
+
+<details>
+<summary>Can't list a parent directory</summary>
+
+- On SELinux systems, listing a parent directory may fail even though specific
+  files are accessible. Probe individual paths instead (for example, `stat` or
+  `cat`).
 
-- Can’t list a parent directory
-  - On SELinux systems, listing a parent directory may fail even though specific
-    files are accessible. Probe individual paths instead (for example, `stat` or
-    `cat`).
+</details>
 
 ## Related information