Configuration

OpenHound uses DLT configuration management, which lets you set parameters through configuration files, environment variables, or both. The following sections cover common OpenHound parameters and how to configure them for your deployment. You configure OpenHound in nearly the same way whether you run it as a containerized service or as a standalone CLI application.

Configuration management

OpenHound and DLT use a TOML-based configuration layout that organizes settings into sections based on the component or feature. Each top-level section defines defaults for a specific phase during the collection/conversion pipeline. The syntax allows for nested sections, collector-specific configurations, and collector-specific overrides. For example, the [extract] parallel worker count can be set globally for all collectors, but can also be increased/decreased for a specific collector. Configuration precedence follows a global-to-specific order: a collector-specific override in [sources.source.<collector>.extract] takes priority over a global setting in [extract], which in turn takes priority over the built-in default. OpenHound reads configuration from DLT files, environment variables, or both. Keep non-sensitive settings and secrets in separate files:

File	Purpose
`config.toml`	Non-sensitive runtime settings shared across collectors. Its contents differ by edition.
`secrets.toml`	The single secrets file each collector run reads. Its contents differ by edition.
Collector key files	Extra key material referenced from `secrets.toml`, such as a GitHub App `.pem` private key or an Okta JSON key file. Required only by collectors that use key-based authentication.

For Docker Compose deployments, create the DLT files under ~/.dlt on the host.

`config.toml`

The config.toml file contains non-sensitive runtime settings that apply to all collectors. It can also hold the BloodHound Enterprise tenant URL for scheduled collection.

Edition-specific settings

The following example configuration sets global values for runtime, normalize, and load, then overrides the extract worker count for the Okta and GitHub collectors.

Enterprise
Community

The primary difference between BloodHound Enterprise and BloodHound Community editions is that the destination.bloodhoundenterprise setting applies to BloodHound Enterprise scheduled collection only. It authenticates each collector container to your tenant.

Enterprise ~/.dlt/config.toml

[runtime]
log_level = "INFO"
log_rotate_when = "midnight"
log_interval = 1

# HTTP retry/backoff for source requests; rides out API rate limits
# (e.g. GitHub during large collections) instead of failing the run.
request_max_attempts = 15
request_backoff_factor = 1.3
request_max_retry_delay = 900

# Default: logs are set to human readable text
# To switch to structured JSON instead, uncomment the line below (must be uppercase "JSON")
# log_format = "JSON"

[destination.bloodhoundenterprise]
url = "https://your-tenant.bloodhoundenterprise.io"

[extract]
workers = 4

[sources.source.github.extract]
workers=2

[sources.source.okta.extract]
workers=12

[normalize]
workers = 4

[load]
delete_completed_jobs=true
truncate_staging_dataset=true
workers=2

OpenHound supports the following environment variables for the destination.bloodhoundenterprise section:

Destination Option	Environment Variable	Description
`url`	DESTINATION__BLOODHOUNDENTERPRISE__URL	The URL of the BloodHound Enterprise tenant. Store this non-sensitive value in `config.toml`.
`collector_name`	DESTINATION__BLOODHOUNDENTERPRISE__COLLECTOR_NAME	Required for scheduled collection. Identifies the extension this scheduler runs, such as `github`, `jamf`, or `okta`.

The following example is nearly identical to the Enterprise example, except that it omits the destination.bloodhoundenterprise section.

Community ~/.dlt/config.toml

[runtime]
log_level = "INFO"
log_rotate_when = "midnight"
log_interval = 1

# HTTP retry/backoff for source requests; rides out API rate limits
# (e.g. GitHub during large collections) instead of failing the run.
request_max_attempts = 15
request_backoff_factor = 1.3
request_max_retry_delay = 900

# Default: logs are set to human readable text
# To switch to structured JSON instead, uncomment the line below (must be uppercase "JSON")
# log_format = "JSON"

[extract]
workers = 4

[sources.source.github.extract]
workers=2

[sources.source.okta.extract]
workers=12

[normalize]
workers = 4

[load]
delete_completed_jobs=true
truncate_staging_dataset=true
workers=2

Each OpenHound scheduler runs one collector, so scheduled collection needs one collector_name value per scheduler container.The example Docker Compose services set this value for you when you start a service such as scheduler-github. Helm and other container deployments must provide the value manually through chart values, environment variables, or the [destination.bloodhoundenterprise] section.

See Runtime settings for the full list of common runtime settings.

`secrets.toml`

Each OpenHound container runs a single collector, so each container needs its own secrets.toml file. To run multiple collectors on one host, keep a separate secrets file per collector, for example:

~/.dlt/secrets_github.toml
~/.dlt/secrets_okta.toml
~/.dlt/secrets_jamf.toml

At runtime, OpenHound always reads the secrets.toml file. The collector-specific secrets files are an authoring convenience on the host. Your deployment mounts the correct one into each container as secrets.toml.

The example Docker Compose files follow this pattern for both BloodHound Enterprise and BloodHound Community. Each service mounts one host secrets file as the container’s secrets.toml and mounts any collector key files (such as github.pem or okta.json) to the paths referenced by the collector credentials. Store these key files outside version control and set the collector’s key path to match the path inside the container.

Edition-specific secrets

The structure of the secrets.toml file is the main configuration difference between BloodHound Enterprise and BloodHound Community editions. The following table summarizes the required sections for each edition:

`secrets.toml` section	Enterprise	Community
`[destination.bloodhoundenterprise]`	Required. Authenticates the collector client that uploads data to your tenant.	Omit. Community writes OpenGraph files to the local filesystem instead of a BloodHound Enterprise destination.
`[sources.source.<collector>.credentials]`	Required. Authenticates to the source system.	Required. Authenticates to the source system.

Community
Enterprise

Because Community collection has no BloodHound Enterprise destination, the collect, preprocess, and convert commands read and write local files, so the secrets file only needs the collector’s source credentials.

Community ~/.dlt/secrets_github.toml

[sources.source.github.credentials]
# GitHub collector credentials for your authentication method.

BloodHound Enterprise requires the destination.bloodhoundenterprise section to authenticate the collector client that uploads data to your tenant. Each collector also needs its own source credentials section.

Enterprise ~/.dlt/secrets_github.toml

[destination.bloodhoundenterprise]
token_id = "client_token_id"
token_key = "client_token_key"

[sources.source.github.credentials]
# GitHub collector credentials for your authentication method.

OpenHound supports the following environment variables for the destination.bloodhoundenterprise section:

Destination Option	Environment Variable	Description
`token_key`	DESTINATION__BLOODHOUNDENTERPRISE__TOKEN_KEY	The API token key generated for the matching OpenHound collector client.
`token_id`	DESTINATION__BLOODHOUNDENTERPRISE__TOKEN_ID	The API token ID generated for the matching OpenHound collector client.

Collector-specific secrets

Each collector requires additional configuration parameters that are unique to its data source. These settings can be defined in the secrets.toml file or supplied via environment variables. For details on the available parameters, refer to the collector-specific configuration documentation using the links below.

Github

View the required configuration parameters for the Github collector.

Jamf

View the required configuration parameters for the Jamf collector.

Okta

View the required configuration parameters for the Okta collector.

Runtime settings

The following configuration parameters are common for all OpenHound deployments and collectors.

Logging modes

OpenHound automatically detects how it’s running and selects a logging mode accordingly, with no configuration required:

Mode	Detected when	Console output	File output
`CLI`	Running interactively in a terminal (TTY)	Rich, human-friendly formatted output	Yes
`CONTAINER`	`LOG_CONTAINER` is set, or `KUBERNETES_SERVICE_HOST` is present (running inside a Kubernetes pod)	Plain text or JSON streamed to `stdout`	Yes
`SERVICE`	None of the above (for example, running as a background/scheduled process)	None	Yes

OpenHound checks for container indicators first, then falls back to a TTY check, and defaults to SERVICE mode otherwise.

To force CONTAINER mode outside of Kubernetes, set the LOG_CONTAINER environment variable to a truthy value (for example, LOG_CONTAINER=true).This is the default behavior in the OpenHound Helm chart and the example Docker Compose files, since KUBERNETES_SERVICE_HOST is only present when running inside a Kubernetes pod.

Log format

By default, OpenHound writes logs as human-readable text. Set log_format to JSON to switch to structured JSON logging, which is useful for ingestion into log aggregation systems. JSON is the only value you can set for this option. To keep the default text logging, omit log_format from your configuration or comment it out.

Runtime Option	Environment Variable	Description
`log_format`	RUNTIME__LOG_FORMAT	The log output format. `JSON` is the only supported value.

The value must be uppercase JSON. DLT’s internal logger performs a case-sensitive check for "JSON" to decide whether to emit its own structured logs.Any other casing (for example, json or Json) leaves DLT’s internal log messages in text format even though OpenHound’s own logs switch to JSON, resulting in mixed-format output.

Log level and rotation

OpenHound implements both time-based and size-based log rotation. When a log is rotated, a timestamp is appended to the filename (for example, openhound.log.2026-02-19) and rotated files are compressed using gzip to reduce disk usage. By default, OpenHound maintains two types of log files:

A global client log (openhound.log) that captures logs for the overall OpenHound service
Collector-specific logs (ext_collector_name.log) that capture logs for individual collectors

The following log configuration options are supported by setting the parameters in the [runtime] section or via environment variables:

Runtime Option	Environment Variable	Description	Default Value
`log_level`	RUNTIME__LOG_LEVEL	Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)	INFO
`log_cli_level`	RUNTIME__LOG_CLI_LEVEL	Console-only verbosity when running in `CLI` mode, independent of `log_level`, which controls file logging.	ERROR
`log_rotate_when`	RUNTIME__LOG_ROTATE_WHEN	The time-based rotation settings. S for seconds, H for hours, D for days and ‘midnight’ for rotating at midnight	midnight
`log_interval`	RUNTIME__LOG_INTERVAL	Rotate every X unit of seconds, hours, days etc. Ignored when rotate_when is ‘midnight’	1
`log_max_bytes`	RUNTIME__LOG_MAX_BYTES	The size-based rotation settings. Rotate the files after an item exceeds the specified byte size. 0 means rotate by time only	5_000_000_000 (5GB)
`log_backup_count`	RUNTIME__LOG_BACKUP_COUNT	The amount of files to keep before deleting the oldest.	14

The code default for log_cli_level is ERROR, which keeps console output nearly silent. We recommend setting it to WARNING for day-to-day use so operators see actionable issues on screen without the noise of full DEBUG/INFO logging.Both example configurations shipped with OpenHound set log_cli_level = "WARNING".

HTTP request parameters

OpenHound uses these [runtime] parameters to control how it handles and retries failing HTTP requests to source APIs.

Runtime Option	Environment Variable	Description	Default Value
`http_show_error_body`	RUNTIME__HTTP_SHOW_ERROR_BODY	Includes the HTTP response body in raised exceptions/logs. Useful for diagnosing API errors from collectors (GitHub, Okta, Jamf). May expose sensitive response data in logs when enabled.	false
`request_max_attempts`	RUNTIME__REQUEST_MAX_ATTEMPTS	Maximum number of retry attempts for a failing HTTP request before OpenHound gives up and fails the pipeline.	5
`request_backoff_factor`	RUNTIME__REQUEST_BACKOFF_FACTOR	Multiplier for the exponential delay between retries. The delay for a given attempt is `backoff_factor * 2^(attempt - 1)` seconds.	1
`request_max_retry_delay`	RUNTIME__REQUEST_MAX_RETRY_DELAY	Upper bound, in seconds, on the computed exponential delay. Prevents the wait time from growing unbounded on later attempts.	300

How retries mitigate API rate limits

OpenHound automatically retries requests that fail with 5xx or 429 status codes, or when the connection is dropped or unreachable. If the API response includes a Retry-After header, OpenHound honors that value instead of the computed backoff delay. The three retry parameters work together as a single exponential-backoff algorithm rather than as independent settings:

request_backoff_factor sets the starting pace of the delay curve. The delay doubles on each subsequent retry attempt (standard exponential backoff).
request_max_retry_delay caps how long any single wait can grow to, so retries don’t stall indefinitely between attempts.
request_max_attempts sets how many times OpenHound rides out this curve before it fails the collection run entirely.

The following table compares the default retry curve to the tuned values shipped in OpenHound’s example configurations:

Attempt	Default (`factor=1`, `max=300s`)	Tuned example (`factor=1.3`, `max=900s`)
1	1s	1.3s
5	16s	20.8s
10	300s (capped)	665.6s
15	— (default stops at attempt 5)	900s (capped)

The example values (request_max_attempts = 15, request_backoff_factor = 1.3, request_max_retry_delay = 900) in the shipped config.toml templates aren’t arbitrary. They were added specifically to work around GitHub API rate-limiting issues encountered during large collections.GitHub’s secondary/abuse rate limits can take several minutes to clear, and the DLT defaults (5 attempts, 300s cap) aren’t enough to ride them out. Raising the attempt count and delay cap lets OpenHound patiently wait out GitHub’s rate limits instead of failing the run.

Example ~/.dlt/config.toml with tuned retry settings

[runtime]
request_max_attempts = 15
request_backoff_factor = 1.3
request_max_retry_delay = 900

If you collect from rate-limit-sensitive sources, particularly GitHub, start from these tuned values rather than the DLT defaults.

Data writing parameters

The data writing parameters specify when and how in-memory data is written to disk during the collection and normalization phase. The following parameters are configured under the [data_writer] section in the configuration file and define the default data writer behavior for the pipeline. Individual pipeline phases, such as the extract and normalize phase, or each individual source can have their own overrides by specifying a different data_writer value in the corresponding section.

Data writer option	Environment Variable	Description	Default Value
`buffer_max_items`	DATA_WRITER__BUFFER_MAX_ITEMS	The maximum amount of items to keep in memory before writing to disk.	5000
`file_max_items`	DATA_WRITER__FILE_MAX_ITEMS	The maximum amount of items to write to a single file before creating a new file.	None
`file_max_bytes`	DATA_WRITER__FILE_MAX_BYTES	The maximum amount of bytes to write to a single file before creating a new file.	None

Example for ~/.dlt/config.toml with data writing overrides

[data_writer]
file_max_items=1000

[normalize.data_writer]
file_max_items=100000

[sources.source.okta.data_writer]
file_max_items=50000

The data_writer parameters directly influence the performance and memory use of the collection/conversion pipeline. Edges and nodes are processed in batches and the amount of processed items is determined by the data_writer parameters.Setting these parameters too low can result in a large amount of small files and increased overhead with less memory usage, while setting them too high can result in increased memory use and slower performance.We recommend experimenting with different values to find the optimal configuration, which typically depends on the size of your environment.

Extract parameters

The extract phase is responsible for collecting data from the data source and generating intermediate (compressed) JSONL files. The extract phase is typically the most time-consuming phase of the pipeline as it involves making API calls to the data source and processing the collected data. The following parameters are configured under the [extract] section in the configuration file. The extract phase can also have its own data writer configuration by setting the data_writer parameter in the [extract] section, which will override the global data writer settings.

Extract option	Environment Variable	Description	Default Value
`workers`	EXTRACT__WORKERS	The amount of concurrent workers used during the collection phase	5

Example for ~/.dlt/config.toml parallel worker overrides

[extract]
workers=5

[sources.source.okta.extract]
workers=10

Normalize parameters

The normalize phase is responsible for converting data times and handling schema evolutions. It standardizes column/table names to be snake_case and is executed automatically between the extract and load phase. The following parameters are configured under the [normalize] section in the configuration file. The normalization phase can also have its own data writer configuration by setting the data_writer parameter in the [normalize] section, which will override the global data writer settings.

Normalize option	Environment Variable	Description	Default Value
`workers`	NORMALIZE__WORKERS	The amount of concurrent workers used during the DLT normalization phase	1
`start_method`	NORMALIZE__START_METHOD	The subprocess starting method (relevant for OS)	fork

Load parameters

The load phase is responsible for loading the converted OpenGraph files into the destination, which is either set to local file system or BloodHound Enterprise. The following parameters are configured under the [load] section in the configuration file.

Load option	Environment Variable	Description	Default Value
`delete_completed_jobs`	LOAD__DELETE_COMPLETED_JOBS	Whether to delete completed jobs after a pipeline has completed.	false
`truncate_staging_dataset`	LOAD__TRUNCATE_STAGING_DATASET	Whether to truncate the staging dataset after loading data into the destination.	false
`workers`	LOAD__WORKERS	The amount of concurrent workers used during the loading phase, is when uploading data to BloodHound Enterprise	1

Get Started with BloodHound

Install a Data Collector

Collect Data

OpenGraph

OpenHound

Analyze Attack Path Data

Manage BloodHound

API & Integrations

On-premises BloodHound Enterprise

Resources

Configuration management

`config.toml`

Edition-specific settings

`secrets.toml`

Edition-specific secrets

Collector-specific secrets

Github

Jamf

Okta

Runtime settings

Logging modes

Log format

Log level and rotation

HTTP request parameters

How retries mitigate API rate limits

Data writing parameters

Extract parameters

Normalize parameters

Load parameters

​Configuration management

​config.toml

​Edition-specific settings

​secrets.toml

​Edition-specific secrets

​Collector-specific secrets

Github

Jamf

Okta

​Runtime settings

​Logging modes

​Log format

​Log level and rotation

​HTTP request parameters

​How retries mitigate API rate limits

​Data writing parameters

​Extract parameters

​Normalize parameters

​Load parameters

Configuration management

`config.toml`

Edition-specific settings

`secrets.toml`

Edition-specific secrets

Collector-specific secrets

Runtime settings

Logging modes

Log format

Log level and rotation

HTTP request parameters

How retries mitigate API rate limits

Data writing parameters

Extract parameters

Normalize parameters

Load parameters