Skip to main content

Hide sensitive files with .thvignore

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.

Create an ignore file​

Create a file named .thvignore at the root of the directory you intend to mount. Use simple, gitignore-like patterns:

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

thv run --volume ./my-project:/projects filesystem

To print resolved overlay targets for debugging:

thv run --volume ./my-project:/projects \
  --print-resolved-overlays \
  filesystem

The resolved overlays are logged to the workload's log file. For a complete list of options, see the thv run command reference.

Global ignore patterns​

You can define global ignore patterns in a platform-specific location:

  • Linux: ~/.config/toolhive/thvignore
  • macOS: ~/Library/Application Support/toolhive/thvignore
  • Windows: %LOCALAPPDATA%\toolhive\thvignore

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:

thv run --ignore-globally=false --volume ./my-project:/projects filesystem
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
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).