hublot-kit

module
v0.2.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 24, 2026 License: MIT

README

Hublot-Kit

Security: installing Hublot-Kit gives it root on the host. It talks to the Docker socket and reads the files of your containers. Keep it on 127.0.0.1 and reach it through an SSH tunnel or an HTTPS reverse proxy. Read the security model first.

Lire en français

Explore the inside of the Docker containers of a server from a browser, without a terminal. Pick a container and see its files, what changed since its image, its logs and its configuration; browse the files of an image; take a photo of a container's files and compare it later.

Container list, dark theme File explorer with the changes since the image

What it does (v0.2)

  • Containers: name, image, Compose project, status, ports, uptime; tabs, filters, key figures (files, image size, container size) and labels, filtered.
  • Files: the whole tree of a running or a stopped container, text and image preview, size, owner, permissions.
  • Download a file, or a folder as a tar archive.
  • Edit a text file or upload a file, after a confirmation that names the container and the path.
  • Diff with the image: what was added, modified or deleted since the image, and the line diff of a modified file between its version in the image and in the container.
  • Logs: live stream, search, pause and resume, download.
  • X-ray: image, state, command, environment (secrets masked, revealed one at a time and logged), ports, networks, mounts.
  • Images: every image of the daemon, its layers and its configuration (masked), and its files read only, without creating a container.
  • Snapshots: a photo of a container's files (metadata and a keyed fingerprint, never the content), compared with another photo or with the current container.
  • Secrets: the names of everything the agent masks, across every container; never a value unless revealed, one at a time.
  • Search (Ctrl K): containers, Compose projects, pages, and the files of an index already built.
  • Themes: dark by default, light on demand, kept in the browser.
  • Read-only mode (--read-only): no write into the containers; the interface shows the agent's real state.

One server, one user, an interface in English and French, a single static binary with the interface embedded, no database, no telemetry. Processes and resources, start/stop and a web terminal are postponed after v0.2.

Quick start

Requirements: Linux amd64 or arm64, kernel 5.6 or later (5.8 to edit files of a running container), Docker Engine with API 1.44 or later, overlay2 or containerd storage. The same command works on AppArmor (Ubuntu, Debian) and SELinux (Fedora, RHEL) hosts; why each option is needed.

docker run -d --name hublot-kit \
  --pid=host --cgroupns=host --cap-add SYS_PTRACE \
  --security-opt apparmor=unconfined \
  --security-opt label=disable \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v hublot-data:/data \
  -p 127.0.0.1:7878:7878 \
  ghcr.io/levy-cmd/hublot-kit:0.1

The access token is printed once, on the first start, on the line Access token (shown only once): ….

docker logs hublot-kit

From your computer, open a tunnel, then browse to http://127.0.0.1:7878 and paste the token.

ssh -L 7878:127.0.0.1:7878 user@server

Prefer a plain binary run by systemd? See Binary and systemd.

Documentation

  • A tour of the interface: the layout, the search, the panels, the Images, Secrets and Snapshots pages, the theme, read-only mode as the interface shows it.
  • Installation: Docker, binary and systemd, reverse proxy, token, upgrade, uninstall, verifying the signatures and SBOMs of a release.
  • Security model: what the agent can do, what protects it, how to expose it.
  • Known limitations: what Hublot-Kit does not do, or does not detect.

Development

Requirements: Go 1.27 or later, Node 24 (22.17 or later), Docker. The Go code that touches /proc only runs on Linux: make test-linux runs it as root in a golang container.

make test
make build
make test-linux

On macOS (Docker Desktop), /proc/<pid>/root only exists inside Docker's virtual machine, so the agent runs in a container: make web && scripts/dev-agent.sh. The interface in development mode proxies to the agent on 127.0.0.1:7878: cd web && npm run dev. The technical specs are in docs/superpowers/specs (in French): v0.1, the reference, and v0.2, its complement.

License

MIT

Directories

Path Synopsis
cmd
hublot command
Command hublot is the Hublot-Kit agent.
Command hublot is the Hublot-Kit agent.
internal
api
Package api exposes the agent's HTTP API.
Package api exposes the agent's HTTP API.
audit
Package audit writes the append-only JSON-lines audit log.
Package audit writes the append-only JSON-lines audit log.
auth
Package auth holds the access token, sessions and the login rate limiter.
Package auth holds the access token, sessions and the login rate limiter.
config
Package config reads the agent's options from flags and HUBLOT_* variables.
Package config reads the agent's options from flags and HUBLOT_* variables.
dockerx
Package dockerx is the agent's only gateway to the Docker Engine API.
Package dockerx is the agent's only gateway to the Docker Engine API.
files
Package files is the agent's only writer (spec §4, §5.3, §7): read-only mode, link checks, If-Match, audit, then PutArchive, in one function per write.
Package files is the agent's only writer (spec §4, §5.3, §7): read-only mode, link checks, If-Match, audit, then PutArchive, in one function per write.
fsview
Package fsview reads the files of a container (spec §4, §5): one interface, procfs for a running container, tarindex for a stopped one (plan Explorateur 2).
Package fsview reads the files of a container (spec §4, §5): one interface, procfs for a running container, tarindex for a stopped one (plan Explorateur 2).
secrets
Package secrets masks the values the radiography shows (F7, spec §7): an environment variable whose name says it is a secret, or whose value is a URL with user information, never leaves the agent unless revealed.
Package secrets masks the values the radiography shows (F7, spec §7): an environment variable whose name says it is a secret, or whose value is a URL with user information, never leaves the agent unless revealed.
snapshot
Package snapshot takes, keeps and lists the snapshots of spec v0.2 §5.7: a manifest of the files of a container at one moment, with a keyed HMAC of each regular file, never its content.
Package snapshot takes, keeps and lists the snapshots of spec v0.2 §5.7: a manifest of the files of a container at one moment, with a keyed HMAC of each regular file, never its content.
web
Package web serves the compiled SvelteKit UI embedded in the binary.
Package web serves the compiled SvelteKit UI embedded in the binary.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL