Hostpanel

hostpanel

hostpanel looks after a single host: Docker daemon and container state, Compose projects, basic host information, file search, ZFS pools, and journal logs. It exposes all of that through two action-router tools, flux and scout, and the same two routers on the command line. One binary serves both faces.

This is a labelled core subset of a larger documented surface. The implemented actions are listed below; every other documented action is omitted from this subset and is named in the build report and in the spec fixture, not silently dropped.

Only the local host is served. A host parameter, when supplied, must be local; remote SSH targets are not part of this subset. Processes are started with an argument array only — no command string ever goes through a shell.

Install

npx @reneturcios/hostpanel help

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/hostpanel

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead, and mount the Docker socket if you want the flux actions to reach a real daemon.

CLI

hostpanel flux docker infohostpanel flux docker versionhostpanel flux container list --params '{"state":"running"}'hostpanel flux container inspect --params '{"container_id":"abc123"}'hostpanel flux host infohostpanel flux compose list
hostpanel scout nodeshostpanel scout exec --params '{"command":"hostname"}'hostpanel scout exec --params '{"command":"cat","args":["/etc/hostname"]}'hostpanel scout find --params '{"path":"/srv","pattern":"*.log","limit":20}'hostpanel scout zfs poolshostpanel scout logs journal --params '{"unit":"docker","lines":50}'
hostpanel helphostpanel --version

Successful calls print a JSON object with the argv that ran and its captured stdout, stderr, and exitCode; nodes and the help actions print their local answers directly. Exit codes: 0 on success, 1 when a call fails (including a refused command or a non-zero child exit), 2 for usage errors.

MCP server

npx -y @reneturcios/hostpanel mcp

MCP client configuration:

{  "mcpServers": {    "hostpanel": {      "command": "npx",      "args": ["-y", "@reneturcios/hostpanel", "mcp"]    }  }}

Tools

Both tools take a required action, an optional subaction, and an optional params object. Parameter names inside params follow the original per-action tables (host, container_id, state, name_filter, image_filter, label_filter, path, pattern, depth, limit, command, args, pool, lines, unit, priority, since, until, grep).

The exec allowlist

scout exec runs read-only inspection commands only. The full allowlist is 18 commands: cat, head, tail, grep, rg, ls, tree, wc, uniq, diff, stat, file, du, df, pwd, hostname, uptime, and whoami. Anything else — including git, shells, interpreters, and mutating tools — is refused before any process starts. The command must be a single name; arguments travel separately in the args array and are passed as argv, never interpolated into a shell string.

Development

npm installnpm run build   # tsc -> dist/npm test        # node test runner over test/*.test.ts, fake executor onlynpm run dev     # run the CLI from source via tsx

Tests inject a fake executor, so the suite records the argv each action would run and proves refused commands never reach the executor. No Docker daemon, ZFS pool, or journal is needed — and no live host result is claimed by the test suite.

License

MIT — see LICENSE.