--- title: Self-Hosted Deployment Guide slug: self-hosted-deployment-guide docTags: createdAt: 2026-05-12T03:47:19.044Z --- 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. ## Core Concepts ### Concurrency Concurrency sets the number of worker threads the scanner runs in parallel for scanning and detection. Think of concurrency as your throughput dial: | | Higher concurrency | Lower concurrency | | ------------------ | --------------------------- | -------------------- | | **Parallel work** | More | Less | | **Scan speed** | Faster (if resources allow) | Slower | | **Resource usage** | Higher CPU and memory | Lower CPU and memory | **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. ```yaml trufflehogAddress: trufflehogScannerGroup: trufflehogScannerToken: thog-agent-xxxxxxxxxxxxxxxxxx logJson: true logLevel: info concurrency: 4 ``` :::Paragraph{indent="1"} **Important notes** ::: - TruffleHog scanners are designed to fully utilize the available concurrency. - Some integrations fetch data via APIs (e.g., Jira, Confluence) that enforce server-side rate limits. In these cases, your CPU may not be fully saturated because TruffleHog respects those limits. - Monitor your local TruffleHog logs for rate-limit and timeout errors, and increase concurrency only as your scans demand it and your source APIs can tolerate it. ### CPU and Memory 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** - **Give CPU generous headroom.** Scans are bursty by nature, and under-provisioning CPU can cause jobs to throttle mid-run or take significantly longer to complete. - **Set memory limits conservatively.** Over-allocating memory wastes resources, but setting limits too low can result in Out of Memory (OOM) errors that kill scan jobs. - **Monitor and adjust.** Use the sizing recommendations in the next section as a starting point, then tune based on observed usage in your environment. ### Ephemeral Storage 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** - **Start with at least 50 GB.** This is a safe baseline for most deployments and accommodates moderately sized repositories. - **Increase for large repositories.** Monorepos and repositories with deep Git history can require significantly more space. If you're scanning a single repo larger than 10 GB, plan for storage well above the baseline. - **Account for parallel scans.** Higher concurrency means multiple sources may be cloned or extracted simultaneously, increasing peak storage usage. ## Sizing Recommendations 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. | Tier | Developers | Sources | CPU | RAM | Ephemeral Storage | | ----------- | ---------- | ------- | ---- | --------- | ----------------- | | **Small** | 50–250 | 1–4 | 1–4 | 0.5–2 GB | 50 GB+ | | **Medium** | 251–1,000 | 5–15 | 1–8 | 2–8 GB | 50 GB+ | | **Large** | 1,000+ | 16+ | 8–16 | 8–32 GB | 100 GB+ | | **X-Large** | 5,000+ | 32+ | 16+ | 16–32 GB+ | 200 GB+ | 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. ## Deployment Options 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. ### Kubernetes (recommended) We recommend deploying TruffleHog on Kubernetes using our [Helm chart](https://github.com/trufflesecurity/helm-charts). 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** - **Simple setup.** Creates the deployment and Vertical Pod Autoscaler (VPA) in a single install. - **Templated configuration.** All settings live in one place and can be version-controlled. - **Open source.** Customers can submit PRs for improvements. - **Works as a template engine** even without Helm installed. - **VPA integration.** Available on Google GKE, AWS AKS, and EKS, with both recommendation mode and automatic scaling. Upper limits can be set to prevent runaway resource usage. (VPA can be disabled if required.) **Helm chart parameters** For the [full list of Helm chart parameters](https://github.com/trufflesecurity/helm-charts/blob/main/trufflehog/values.yaml), see our chart documentation. Below are some commonly adjusted defaults: | Parameter | Default | | --------------------------- | ------- | | `replica` | 1 | | `resources.requests.cpu` | 4000m | | `resources.requests.memory` | 16Gi | | `resources.limits.cpu` | 12000m | | `resources.limits.memory` | 48Gi | | `vpa.enabled` | true | | `vpa.minAllowed.cpu` | 4000m | | `vpa.minAllowed.memory` | 16Gi | | `vpa.maxAllowed.cpu` | 12000m | | `vpa.maxAllowed.memory` | 48Gi | **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. ### Linux Host 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](https://docs.trufflesecurity.com/linux-host) for installation steps and configuration details. ### Docker 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](https://docs.trufflesecurity.com/docker) for setup instructions. ## Scanner Group Strategy 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. ### Single scanner group with multiple sources **When to use** - Cost-effective: one host, one scanner group - Lower operational management overhead - The most common starting point for small and medium deployments **Trade-offs** - Single point of failure: if the scanner goes down, all sources stop scanning **Example configuration** A single scanner group handles multiple sources within one config.yml: ```yaml trufflehogAddress: trufflehogScannerGroup: primary-scanner trufflehogScannerToken: thog-agent-xxxxxxxxxxxxxxxxxx logJson: true logLevel: info sources: - connection: '@type': type.googleapis.com/sources.GitHub endpoint: https://github.ourbusiness.com token: XXXXXXXXXXXXXXXXXXXXXXXXXX name: GitHub scanPeriod: 12h type: SOURCE_TYPE_GITHUB verify: true - connection: '@type': type.googleapis.com/sources.Confluence endpoint: https://confluence.ourbusiness.com token: XXXXXXXXXXXXXXXXXXXXXXXXXX name: Confluence scanPeriod: 24h type: SOURCE_TYPE_CONFLUENCE verify: true ``` ### Multiple scanner groups, one source per scanner **When to use** - You want each scanner dedicated to a single source type (e.g., one for GitHub, one for Docker, one for Confluence) - Failure isolation: an issue with one scanner doesn't affect the others - Easier troubleshooting and observability per source type - Resource allocation for large repos (e.g., monorepos) - Logical separation by business unit or source category **Trade-offs** - All scanners share the host's CPU, memory, and network, so heavy load on one scanner can still affect the others - More configuration overhead than a single scanner group **Example configuration** Each scanner runs with its own config.yml, its own scanner group, and a single source. *GitHub scanner (config-github.yml):* ```yaml trufflehogAddress: trufflehogScannerGroup: github-scanner trufflehogScannerToken: thog-agent-xxxxxxxxxxxxxxxxxx logJson: true logLevel: info sources: - connection: '@type': type.googleapis.com/sources.GitHub endpoint: https://github.ourbusiness.com token: XXXXXXXXXXXXXXXXXXXXXXXXXX name: GitHub scanPeriod: 12h type: SOURCE_TYPE_GITHUB verify: true ``` *Confluence scanner (config-confluence.yml):* ```yaml trufflehogAddress: trufflehogScannerGroup: confluence-scanner trufflehogScannerToken: thog-agent-yyyyyyyyyyyyyyyyyy logJson: true logLevel: info sources: - connection: '@type': type.googleapis.com/sources.Confluence endpoint: https://confluence.ourbusiness.com token: YYYYYYYYYYYYYYYYYYYYYYYYYY name: Confluence scanPeriod: 24h type: SOURCE_TYPE_CONFLUENCE verify: true ``` ### Multiple scanner groups across multiple hosts 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** - A single source type's resource needs are large enough to dominate a shared host (e.g., GitLab or GitHub clones of large monorepos requiring 32+ GB) - Network segmentation requirements (e.g., the Confluence scanner needs to live in an isolated zone that can reach on-prem Confluence Server, while GitHub scanning needs access to a different VPC) - Compliance requirements that mandate hard isolation between source types' credentials and processing - Scan windows differ enough to justify scaling instances independently (e.g., spot instances for overnight GitLab scans, steady-state for daytime Jira scans) **Benefits** - Strongest isolation: scanner groups don't compete for CPU, memory, or network at any level - A heavy workload on one host can't affect the others **Trade-offs** - Most expensive option: one VM (or dedicated pod) per scanner group - More operational overhead: more hosts to monitor, patch, and maintain **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). - Failure isolation works as expected: if one scanner pod runs out of memory or crashes, only that pod goes down. Kubernetes restarts it, and the other scanner groups keep running uninterrupted. - Trade-offs: more complex to manage ## Resource Requirements Calculator For an initial sizing estimate tailored to your environment, use our [Resource Requirements Calculator](https://docs.google.com/spreadsheets/d/1JvQZ6fGrGdHSv6HTsSsJWklTE33WWFVNuMa8mOdGi_U/edit?gid=0#gid=0). 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.