Self-Hosted Deployment Guide

Whether you're deploying TruffleHog for the first time or optimizing an existing setup, this guide covers core concepts, sizing recommendations, deployment options, and scanner group strategy.

The sizing recommendations and resource guidance throughout this guide are based on real-world customer deployments across small, medium, and large organizations. Use them as a starting point, your specific requirements may vary based on the sources you scan, the size of your repositories, and your scan frequency.

Concurrency sets the number of worker threads the scanner runs in parallel for scanning and detection.

Think of concurrency as your throughput dial:

How to configure it

Concurrency is set in your configuration file (typically config.yml). By default, it matches the number of CPU cores detected on the host running TruffleHog. To override the default, set the value explicitly in your config.yml.

Example

If a customer sets concurrency to 4 in their config.yml, TruffleHog runs 4 worker threads in parallel, each independently scanning and detecting secrets. For example, with 4 sources configured, the scanner can run one job per source simultaneously. Concurrency is set in your configuration file (typically config.yml). By default, it matches the number of CPU cores detected on the host running TruffleHog. To override the default, set the value explicitly in your config.yml.

CPU usage can vary widely during a scan. The same customer may see usage range from 3 CPUs to 15+ CPUs across different scans, depending on the source type, repository size, and concurrency settings.

Memory usage tends to be more predictable but can spike when scanning large repositories or processing high volumes of findings.

Sizing guidance

Ephemeral storage is temporary disk space TruffleHog uses during a scan — primarily for cloning Git repositories, extracting archives, and writing intermediate scan data to the system's temporary directory. This data is discarded once the scan completes.

Ephemeral storage requirements are primarily driven by Git-based scanning. API-based sources (e.g., Slack, Jira, Confluence) stream data and do not require significant temporary disk space.

Sizing guidance

The following recommendations are sized by developer headcount and number of sources scanned. Use them as a starting point and adjust based on your observed resource usage.

These ranges reflect typical deployments, but actual requirements depend on your specific scan workload — particularly repository size, Git history depth, and scan frequency. Monitor your scanner's resource usage over the first few scans and adjust accordingly.

TruffleHog can be self-hosted in three environments: Kubernetes, a Linux host, or a Docker container. We recommend Kubernetes for most production deployments because of its built-in scaling, recovery, and resource management capabilities.

We recommend deploying TruffleHog on Kubernetes using our Helm chart. A Helm chart defines, installs, and manages applications on Kubernetes, and ours handles the deployment, autoscaling, and configuration of TruffleHog in a single install. For infrastructure as code, the Terraform Helm provider works seamlessly with our charts.

Why Helm

Helm chart parameters

For the full list of Helm chart parameters, see our chart documentation. Below are some commonly adjusted defaults:

A note on VPA and OOM

Vertical Pod Autoscaler (VPA) in Auto mode requires a pod restart to apply new resource limits, so it does not prevent the initial Out of Memory (OOM) event. Instead, it prevents the next OOM after the pod is rescheduled with more headroom. No cloud service dynamically expands a running container's memory ceiling mid-execution without a restart.

Kubernetes manifests (fallback)

If Helm is disallowed by your platform policy, you can deploy TruffleHog using a raw Kubernetes manifest applied via kubectl apply. Note that this approach does not include VPA or any of the Helm chart helpers, and configuration must be managed manually.

TruffleHog can be deployed directly on a Linux host for simpler setups or environments where Kubernetes isn't available. See the Linux Host deployment guide for installation steps and configuration details.

TruffleHog is also available as a Docker container, which can be useful for testing, CI/CD pipelines, or environments that don't require full orchestration. See the Docker deployment guide for setup instructions.

Every deployment has unique requirements, and the right scanner group strategy depends on your scan volume, source mix, isolation needs, and operational tolerance. Below are common patterns we've seen across customer deployments. Use them as general guidance — your specific requirements may differ.

When to use

Trade-offs

Example configuration

A single scanner group handles multiple sources within one config.yml:

When to use

Trade-offs

Example configuration

Each scanner runs with its own config.yml, its own scanner group, and a single source.

GitHub scanner (config-github.yml):

Confluence scanner (config-confluence.yml):

Recommended for heavy, regulated, or network-segmented enterprise deployments. Each scanner group runs on its own dedicated host (or, in Kubernetes, its own pod).

When to use

Benefits

Trade-offs

Kubernetes variation: single cluster, separate pods

The same isolation pattern can be achieved within a single Kubernetes cluster by running each scanner group as its own deployment with separate pods and dedicated resource requests/limits. Each scanner group is typically dedicated to a single source type (e.g., Jira, Confluence, GitLab).

For an initial sizing estimate tailored to your environment, use our Resource Requirements Calculator. The calculator takes inputs like organization size and source mix and returns a recommended starting configuration, which you can then refine based on the guidance in this document.