hostxray 0.0.1

Best-effort host specification capture for environment comparison, troubleshooting, and LLM context.

hostxray

hostxray collects a best-effort, privacy-aware machine specification for environment comparison (dev/uat/prod), troubleshooting, and providing LLM context.

• Standard library first
• Optional enrichment via extras (pip install hostxray[full])
• Best-effort collection with graceful degradation (never crash)
• Deterministic, JSON-serializable output
• Safe mode (default) redacts sensitive identifiers

This README is intentionally self-contained for PyPI. The docs/ folder (on GitHub) has deeper, field-by-field guidance, but you shouldn’t need it to get started.

Install

pip install hostxray
# Optional extras
pip install hostxray[full]

Quickstart (CLI)

Collect a standard, safe-by-default spec as JSON:

hostxray --format json --profile standard

Collect a more complete spec (may include identifying values):

hostxray --format json --profile full --unsafe

Targeted redaction (even in unsafe mode):

hostxray --format json --profile full --unsafe --redact hostname mac ip user serial

Quickstart (Python)

from hostxray import collect_spec

spec = collect_spec(profile="standard")
print(spec.to_json(indent=2))

Key concepts (quick reference)

Profiles

Profiles control what to attempt to collect.

• minimal: fastest, capacity-oriented inventory
• standard: capacity-focused inventory (no utilization snapshot)
• full: includes utilization snapshot (e.g. CPU/mem/disk %), plus additional best-effort enrichment

If a data source is unavailable (missing permissions, missing optional dependency, unsupported platform), hostxray skips it and continues.

On Windows, standard/full also attempt best-effort hardware enrichment via PowerShell/CIM when available (for example: GPU inventory, BIOS/baseboard, NIC link speed, and disk model/bus/media type).

Safe mode vs unsafe

By default, hostxray runs in safe mode and redacts common identifiers.

• Safe mode (default): returns a useful spec while redacting sensitive identifiers
• Unsafe mode (--unsafe / API option): may include identifying values like hostname, usernames, MAC addresses, IPs, serials (depending on platform and availability)

Redaction controls

You can explicitly redact categories:

• hostname
• user
• ip
• mac
• serial

(Exact available categories may evolve; the CLI --help is the source of truth for your installed version.)

Output guarantees

• JSON-serializable, deterministic structure
• Designed to be stable for diffing across machines
• Collection is best-effort; missing fields are expected and normal

Extras (optional enrichment)

hostxray works with the standard library alone. Installing extras enables additional collectors.

pip install hostxray[full]

If you’re distributing this in a locked-down environment, you can stay on the base install and still get a useful baseline.

CLI

hostxray --help

Documentation

If you’re viewing this on GitHub, deeper references are available:

• docs/README.md: field-by-field guidance and sources
• docs/USAGE.md: CLI and API usage
• docs/EXTRAS.md: what hostxray[full] improves