hostlens

HostLens

HostLens is a small MCP server for live Linux host, systemd service, and local Docker status. It starts in read-only mode. An administrator can enable two narrowly scoped repairs: restart an exact systemd service or a Docker container identified by its full ID.

The gateway authenticates bearer tokens and enforces active profile grants for both tool discovery and calls. A separate Docker observer exposes only named reads from the mixed Docker API. A separate repair worker checks role, profile, and live target again before a restart. Bounded service and container logs need separate grants. There is no generic shell, filesystem read, or Docker API tool. Observations are request scoped and report unavailable sources explicitly.

Linux amd64 and arm64 are supported now. The shared CLI, gateway, authorization, and MCP packages build on macOS and Windows; those platforms need native status, identity, and repair adapters before they can run HostLens.

Start

Build a development candidate with make package, or use the 0.6.0 release. Its configuration schema is version 2, separate from the product release number. Follow the installation guide for download verification, preview and apply, service startup, and a first MCP request. Existing 0.5.0 installations require the upgrade guide; the MCP catalog and configuration change.

hostlens --help
hostlens status
sudo /usr/local/bin/hostlens config validate --config /etc/hostlens/config.yaml
sudo /usr/local/bin/hostlens token create --name first-client --roles observe --expires "$(date -u -d '+30 days' '+%Y-%m-%dT%H:%M:%SZ')"

The default endpoint is http://127.0.0.1:8080/mcp with bearer authentication. The operations guide lists the tools, profile rules, limits, and a first request. The installation guide explains repair activation. Generated tool schemas are checked against the SDK registry during validation. hostlens uninstall previews safe removal; hostlens uninstall --apply stops the packaged services and removes verified HostLens files while retaining administrator data and service identities.

Develop

Use the repository's Makefile or lowercase justfile; the common targets call the same scripts or tools independently. Tests, systemd acceptance, and private Docker fixtures run in disposable containers. No validation target installs HostLens on the development host or changes its systemd units.

make deps
make test-image
make test
make package
make verify-archives

See validation, release engineering, and the current OpenSpec requirements. The tag workflow publishes only after its validation passes.

License

Apache-2.0. NOTICE and the release archives record attribution and dependency licenses.