Configuration reference

ParseHawk service settings are typed with Pydantic and use the PARSEHAWK_ prefix. Values are read when each process starts.

Service environment variables

Environment variable	Type	Default	Description
PARSEHAWK_DATA_DIR	string	data	Directory for the database, uploaded files, secrets, and runtime state.
PARSEHAWK_DATABASE_PATH	string or null	—	SQLite database path. Defaults to <data_dir>/parsehawk.db.
PARSEHAWK_LOG_LEVEL	string	INFO	Python logging level for ParseHawk services.
PARSEHAWK_LOG_MODEL_IO	boolean	false	Log model prompts and responses. May expose sensitive document content.
PARSEHAWK_SECRET_KEY	string or null	—	Encryption key override for stored provider secrets. Sensitive value; never expose it in logs or docs.
PARSEHAWK_INFERENCE_ENGINE	string	none	Bundled inference engine. Use ‘vllm’ or ‘none’.
PARSEHAWK_VLLM_BASE_URL	string	http://127.0.0.1:8080/v1	OpenAI-compatible base URL for the local vLLM runtime.
PARSEHAWK_VLLM_MODEL	string	numind/NuExtract3-W4A16	Model identifier served by the bundled vLLM runtime.
PARSEHAWK_VLLM_MAX_TOKENS	integer	2048	Maximum generated tokens per extraction request. Constraint: minimum 1.
PARSEHAWK_VLLM_TEMPERATURE	number	0.2	Sampling temperature for the bundled runtime. Constraint: minimum 0.
PARSEHAWK_VLLM_TIMEOUT_SECONDS	integer	600	Timeout for one model request in seconds. Constraint: minimum 1.
PARSEHAWK_VLLM_MAX_MODEL_LEN	integer	8192	Maximum vLLM context length in tokens. Constraint: minimum 1.
PARSEHAWK_VLLM_MAX_NUM_SEQS	integer	1	Maximum number of sequences vLLM processes concurrently. Constraint: minimum 1.
PARSEHAWK_VLLM_GPU_MEMORY_UTILIZATION	number	0.5	Fraction of GPU memory available to vLLM on NVIDIA systems. Constraint: greater than 0; maximum 1.
PARSEHAWK_VLLM_ENABLE_MTP	boolean	false	Enable multi-token prediction when the selected vLLM model supports it.
PARSEHAWK_VLLM_VENV_DIR	string	~/.cache/parsehawk/vllm-venv	Managed virtual environment for the Linux vLLM runtime.
PARSEHAWK_VLLM_PIP_SPEC	string	vllm==0.23.0	Pinned pip requirement used to provision Linux vLLM.
PARSEHAWK_VLLM_PYTHON_VERSION	string	3.12	Python version used for the managed Linux vLLM environment.
PARSEHAWK_VLLM_METAL_HOME	string	~/.parsehawk/runtimes/vllm-metal	Installation directory for the macOS vLLM Metal runtime.
PARSEHAWK_VLLM_METAL_VERSION	string	0.3.0.dev20260708043308	Pinned vLLM Metal release identifier.
PARSEHAWK_VLLM_METAL_VLLM_VERSION	string	0.24.0	Upstream vLLM version matched by the vLLM Metal release.
PARSEHAWK_NUEXTRACT_KEEP_ALIVE_SECONDS	integer	300	Seconds NuExtract model state remains warm between jobs. Constraint: minimum 0.
PARSEHAWK_PDF_MAX_PAGES	integer	25	Maximum number of PDF pages rendered for one extraction. Constraint: minimum 1.
PARSEHAWK_PDF_RENDER_DPI	integer	170	DPI used when rendering PDF pages to images. Constraint: minimum 1.
PARSEHAWK_TELEMETRY_DISABLED	boolean	false	Disable anonymous usage analytics when true.

Persistent CLI configuration

The CLI stores explicitly set values in ~/.parsehawk/config.json. Override that location with PARSEHAWK_CONFIG_PATH. Environment overrides take precedence when the relevant command loads effective CLI configuration.

Key	Environment override	Default	Description
server.url	PARSEHAWK_API_URL	http://127.0.0.1:8000	Base URL used by CLI health and lifecycle commands for the ParseHawk API.
web.url	PARSEHAWK_WEB_URL	http://127.0.0.1:5173	Base URL used by CLI health and lifecycle commands for the ParseHawk web UI.
runtime.url	PARSEHAWK_VLLM_BASE_URL	http://127.0.0.1:8080/v1	OpenAI-compatible base URL used by runtime inspection commands.
runtime.model	PARSEHAWK_VLLM_MODEL	numind/NuExtract3-W4A16	Model identifier used by runtime inspection and test commands.
data.dir	PARSEHAWK_DATA_DIR	./data in a source checkout; otherwise ~/.parsehawk/data	Directory containing ParseHawk data, logs, and managed process state.
log.level	PARSEHAWK_LOG_LEVEL	INFO	Log level applied to ParseHawk services started by the CLI.

Cross-cutting environment controls

Environment variable	Purpose
PARSEHAWK_CONFIG_PATH	Override the persistent CLI configuration file path.
DO_NOT_TRACK	Disable anonymous telemetry when set to a truthy value.
OTEL_SDK_DISABLED	Disable OpenTelemetry export when set to true.
OTEL_EXPORTER_OTLP_ENDPOINT	Send traces to an external OTLP endpoint.