Install on Linux with NVIDIA

On Linux x86_64 and ARM64, ParseHawk runs the complete stack in Docker Compose, including the vLLM model server.

Requirements

Linux on x86_64 or ARM64
An NVIDIA GPU with 16 GB VRAM minimum; 24 GB or more for larger contexts
NVIDIA driver and NVIDIA Container Toolkit
Docker Engine with the Compose plugin
uv

ParseHawk is verified on an NVIDIA L4 with 24 GB VRAM.

Verify the GPU path

Before installing ParseHawk, these commands must succeed:

nvidia-smi
docker info
docker compose version
uv --version

Also verify that Docker can expose the GPU to a container using the NVIDIA Container Toolkit instructions for your distribution.

ParseHawk also requires the toolkit runtime to be registered with the active Docker daemon. Confirm that nvidia appears in:

docker info --format '{{json .Runtimes}}'

If the toolkit is installed but the runtime is missing, configure and verify it:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker info --format '{{json .Runtimes}}'

For rootless Docker, follow NVIDIA’s rootless-mode configuration instead of modifying the system Docker daemon.

Install the CLI

git clone https://github.com/parsehawk/parsehawk.git
cd parsehawk
uv tool install --editable .

Start and verify

parsehawk start
parsehawk status
parsehawk doctor

The first run downloads the pinned vLLM image and model weights, then profiles GPU memory. Wait for readiness before treating a slow first start as a failure.

The Web UI is available at http://127.0.0.1:5173 and the API at http://127.0.0.1:8000.

Continue to your first Markdown parse or your first JSON extraction.

Tune the runtime

The automatic profile favors reliable startup. Larger GPUs can opt into more context or concurrency:

PARSEHAWK_VLLM_MAX_MODEL_LEN=16384 \
PARSEHAWK_VLLM_MAX_NUM_SEQS=2 \
PARSEHAWK_VLLM_GPU_MEMORY_UTILIZATION=0.6 \
parsehawk restart

Change one dimension at a time and run a representative extraction or parse job after each change. More context, concurrent sequences, and image pages all increase memory pressure.