hostmap creates a safe, read-only architecture map of a Linux host. It is for
reviewers, operators, and AI agents that need evidence about how a machine is
put together without collecting secrets or changing the system.
It generates Markdown plus JSON, then optionally zips the result.
- OS, kernel, package, and language/runtime versions
- systemd services, timers, sockets, listeners, processes, cron, filesystems
- Docker, Docker Compose, Podman, Kubernetes, k3s
- nginx, Apache, Caddy, Traefik, HAProxy, Cloudflare Tunnel, VPN tools
- Git repositories, GitHub/GitLab/Gitea/Forgejo CI files, deploy files
- databases, queues, monitoring, logging, and backup tool presence
- directory-only filesystem maps with heavy and secret paths pruned
hostmap is read-only. It does not restart services, edit files, install
packages, change firewall rules, or make network API calls.
It is an architecture/documentation tool, not a vulnerability scanner.
By default it excludes secret paths, private keys, token files, databases, browser profiles, caches, Docker/containerd stores, build outputs, and large files. Small included config files are redacted line by line.
From a checkout:
python3 -m hostmap --output hostmap-output --mode safeOr install locally:
python3 -m pip install .
hostmap --output hostmap-output --mode safeModes:
safe: default; includes redacted small config/deploy/CI filesparanoid: versions, runtime snapshots, and directory maps onlylocal: safe mode plus extra local VPN config roots with redaction
The generated archive is named like:
hostmap-output/2026-05-20-120000.zip
See docs/prompts.md for prompts users can give to GPT-5.5 Pro, Codex, or another reviewer agent.
The reusable skill lives at skills/hostmap/SKILL.md.
Users can copy skills/hostmap into their Codex skills directory and ask:
Use the hostmap skill to map this Linux machine safely for review.
python3 -m pytest -q
python3 -m hostmap --mode paranoid --output /tmp/hostmap-smoke