hublot-kit

module
v0.1.2 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 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 it was created, its logs and its configuration.

Container list File explorer with the changes since creation

What it does (v0.1)

  • Containers: name, image, status, ports, uptime; filter and search.
  • 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.
  • Changes: what was added, modified or deleted since the container was created.
  • 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.
  • Read-only mode (--read-only): no write at all.

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 planned for 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

  • 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 v0.1 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 spec is in docs/superpowers/specs (in French).

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.
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