Skip to main content

Hide sensitive files

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.

Next steps​

Troubleshooting​

Overlays didn't apply

If a path you expected to be hidden is still visible inside the container:

  • Make sure .thvignore is in the directory you mounted (not a parent or subdirectory).

  • Confirm your patterns match real names relative to the mount source. Remember, **/*.env is not supported, only entries directly under the mount source.

  • Re-run with --print-resolved-overlays and check the workload's log file for the resolved overlay list:

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

If the file you expect to mount isn't showing up in the container at all (as opposed to being hidden), see File system access troubleshooting.

Can't list a parent directory

On SELinux systems, listing a parent directory may fail even though specific files within it are accessible. Probe individual paths instead (for example, stat <PATH> or cat <PATH>) rather than ls <PARENT>.