hive-am 1.11.0 → 1.12.1

package/CHANGELOG.md

@@ -6,6 +6,45 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## [Unreleased]
 
+## [1.12.1] - 2026-10-24
+
+### Added
+
+- **Diagrams of how hive-am works inside.** `docs/diagrams/`, in English and Spanish, has ten pages that each follow a real path through the code: a chat message, a turn, the effective prompt, a delegation, wake-ups and schedules, processes and ports, a source map of `server/src`, the data model, the life cycle of an agent and the providers. Each has a Mermaid diagram, a table that maps every step to a file, a function and a line, the test scripts that cover it and its edge cases. The README and the reference index link to them.
+
+### Changed
+
+- **New hive-am logos.** The README uses the full logo (isotype plus wordmark), and the app logo, favicon and icons use the new isotype. The editable sources and exports are in `docs/brand/`.
+
+### Fixed
+
+- **Cards no longer touch in a resource's Settings.** In the two-column Settings form, a full-width card (such as **Volumes**) sat 2 px under the last card of a column instead of the usual 14 px, so the two looked glued together. The gap is now the same everywhere.
+
+## [1.12.0] - 2026-10-23
+
+### Added
+
+- **Inspect a Docker resource in every mode.** Inspect is now also in **More** for an existing container (it was only there for a container hive-am creates), and it shows the container's **Labels**, grouped as hive-am's, compose's and the rest. It has two panels: **Configured in hive-am**, always there (the settings of a container hive-am creates, the name of an existing one, or what the compose file says about a service), and **What Docker says**, the live detail. A stopped container is inspected as before, without the shell button.
+- **Raw `docker inspect`.** Inspect has a **Raw JSON** tab with the whole `docker inspect`, highlighted like the code explorer (same themes and whitespace setting, a Web Worker for big ones), with line numbers, a search box that jumps from match to match and **Copy JSON**, which copies exactly what is shown. The server hides the value of variables whose name looks like a secret, and the password of a URL with credentials in any other variable (`postgres://user:••••••••@host/db`), until you press **Reveal**; labels and the command are not hidden. Each compose service has it from its own Inspect. New routes: `GET /api/objects/:id/inspect/raw` and `GET /api/docker/inspect?kind=container|image|volume|network&ref=`, open like the other reads of resources (the app is also opened through other names on the network); the hiding above is done by the server, but it is for the screen, not a security boundary: any page can ask for `reveal=1`, and `GET /api/objects/:id/inspect` already carries the variables in the clear.
+- **Pick networks and volumes from Docker.** In **Create a container**, the **Network** is a picker with the networks of this machine and the **Volumes** are rows: a volume of this machine (picked or typed; a new name is created by Docker on the first start, and the row says so, unless Docker is not answering) or a folder, the path in the container and **Read only**. Images, networks and volumes say how many containers use them. A volume row needs both sides: one with only a source or only a path says so, and the server refuses `data:` or `:/data`, which used to fail only in `docker run`. The rows keep the same saved format, so resources saved before show as they were. New routes `GET /api/docker/volumes` and `GET /api/docker/networks`; `GET /api/docker/containers` gives each container's `mounts` and `networks`, and `GET /api/docker/images` each image's `inUse`. Everything here only reads Docker.
+- **Create and delete networks and volumes from the Docker form.** A network that is not on the machine says the container will not start without it and offers **Create network**; a new volume name offers **Create it now**. Each is an immediate action with a notice, labelled `hive-am.created=1` and marked *created by hive-am*; asking again for one that exists changes nothing. A network or a volume hive-am created that no container uses (running or stopped) can be deleted from the suggestions after a confirmation; the server checks the label and the use again against Docker and refuses another's, Docker's own networks, anonymous volumes and anything in use. New routes, local app only: `POST /api/docker/networks`, `POST /api/docker/volumes`, `DELETE /api/docker/networks/:name`, `DELETE /api/docker/volumes/:name`.
+- **Build an image from a Dockerfile.** Under the image of **Create a container**, **Build from a Dockerfile** takes the file, the build folder (its own by default) and the image name (suggested from the folder), runs `docker build` with the label `hive-am.created=1` and picks the image when it ends; only a regular file named like a Dockerfile (`Dockerfile`, `Containerfile`, `Dockerfile.<suffix>`, `<name>.Dockerfile`, its real name too) is built, because a failure shows the last lines of the output. It waits up to 15 minutes, runs the Dockerfile's steps on this machine and may download base images. The folder picker can now list Dockerfiles (`files=dockerfile,containerfile`). New route, local app only: `POST /api/docker/images/build`.
+- **Edit or copy the compose file and a Dockerfile (server).** New routes, local app only (reading included), to read, save and copy the compose file of a compose resource (always the path saved in it, never one from the page) and a Dockerfile (a regular file named like one, its real name too, up to 512 KB). A save is atomic (a temporary file in the same folder, then a rename: the original survives a failed write) and carries the etag read with the file, so a file changed on disk since is a 409 instead of being overwritten. A copy goes next to the original and never replaces a file without `overwrite`; a compose copy can become the resource's file. Saving the compose file does not touch Docker: it answers whether `docker compose config` reads it (an invalid file is saved and marked) and whether services are running.
+- **Edit or copy the compose file and a Dockerfile.** A compose resource has a **File** tab with its compose file in the code editor: **Save** (after a confirmation that names the file), **Save as copy** next to it (the resource can use the copy, on by default) and **Discard**. If the file changed on disk since it was opened you choose to reload it or overwrite it; if services are running, a notice offers **Create again**; a file Docker cannot read is saved and its error shown. In **Build from a Dockerfile**, **Edit** and **Save as copy** open the Dockerfile in the same editor, and a copy becomes the file to build; saving builds nothing. Windows line endings (`\r\n`) and the file's mode are kept when saving. Going to another resource from the list does not ask about unsaved edits. An existing container offers no file editing.
+- **Additional networks and more options of `docker run`.** A container hive-am creates can be connected to **additional networks** besides its main one; they are connected and disconnected in place (`docker network connect / disconnect`, running or stopped, same container), never by creating it again. **More options of docker run** adds a fixed, checked list: labels, user, working folder, entrypoint and hostname; any other option in the settings (such as `privileged`) is refused instead of ignored. The settings of a container saved before give the same `hive-am.cfg` hash as before, so updating does not create any container again.
+- **Create a managed copy of an existing container.** hive-am still never changes a container it did not create; **Create a managed copy** (in **More** and in its Settings) reads its `docker inspect` and opens the form of a new container hive-am creates, filled in with its image, ports, named volumes and folders, its own variables, networks, limits and options, and lists what could not be copied (anonymous volumes, random ports). The original is only read. New route, local app only: `GET /api/objects/:id/docker/managed-copy`.
+- **Relations map of a Docker resource.** A new **Relations** tab (every Docker mode) maps the resource's neighbourhood only: its containers (for compose, those of its project), their image, the volumes and the folders of this machine they mount (shown as different kinds of node), their networks and the other containers that share one of those, at most 12 per shared node with *and N more*, while Docker's own networks only count their users. Choosing a node lights what it is joined to and shows its detail below, where **Inspect** (Summary and Raw JSON for hive-am's containers, the raw `docker inspect` for the rest) opens in the same panel; a container of a hive-am resource offers **Edit settings**. Read only, no search and no whole-machine view. `GET /api/docker/containers` now gives each container's `object`, `project` and `service`.
+
+### Changed
+
+- **Save and apply, with a confirmation before a container is created again.** In the Settings of a container hive-am creates, *Save and restart* becomes **Save and apply**, for a running or a stopped container. It first asks what would change: additional networks are applied in place without asking; anything else needs the container to be created again, and a confirmation lists each change and its kind, what is lost (files written inside, logs, restart count, id and IP), the anonymous volumes left behind unmounted and the commands that will run, with secrets hidden. Nothing in Docker changes until it is confirmed, and the server refuses an unconfirmed recreate. **Save** alone still never touches Docker. Containers created from now on carry the label `hive-am.networks=1`, and hive-am keeps their networks as configured: a network connected by hand is disconnected on the next start. New routes, local app only: `POST /api/objects/:id/docker/plan` and `POST /api/objects/:id/docker/apply`.
+- **Inspect explains instead of failing.** A container hive-am has not created yet, an existing container Docker cannot find, a compose service with no container and Docker not installed or not running no longer show a bare error: Inspect shows what is configured and says why Docker has nothing. When the settings changed since hive-am created the container, it says the container will be created again on the next start.
+- **`GET /api/objects/:id/inspect` changed shape.** It answers `{ exists, configured, ... }`: with `exists: true` the detail of `docker inspect` and `cfgStale`, with `exists: false` a `reason` (`not-created`, `not-found`, `no-service`, `no-docker`).
+
+### Removed
+
+- **App templates for Docker resources.** Creating a Docker resource no longer offers **From a template** (the ready-made Redis, PostgreSQL, MySQL and other services), so hive-am shows no predefined catalog of services or images and depends on no registry for one; the form opens in **Create a container**, and the other modes are unchanged. `GET /api/object-templates` and `POST /api/objects/from-template` are gone. A compose resource made from a template keeps working as before: its file stays in the data folder (`stacks/<name>/`) and is shown, started and edited (**File** tab) like any other compose file; nothing is moved or deleted.
+
 ## [1.11.0] - 2026-10-23
 
 ### Added
@@ -302,7 +341,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 - Complete documentation in English and Spanish.
 - npm package with the `hive-am` command.
 
-[Unreleased]: https://github.com/hughcbscrt/hive-am/compare/v1.11.0...HEAD
+[Unreleased]: https://github.com/hughcbscrt/hive-am/compare/v1.12.1...HEAD
+[1.12.1]: https://github.com/hughcbscrt/hive-am/compare/v1.12.0...v1.12.1
+[1.12.0]: https://github.com/hughcbscrt/hive-am/compare/v1.11.0...v1.12.0
 [1.11.0]: https://github.com/hughcbscrt/hive-am/compare/v1.10.1...v1.11.0
 [1.10.1]: https://github.com/hughcbscrt/hive-am/compare/v1.10.0...v1.10.1
 [1.10.0]: https://github.com/hughcbscrt/hive-am/compare/v1.9.1...v1.10.0

package/README.md

@@ -1,9 +1,7 @@
 <p align="center">
-  <img src="web/public/logo.png" alt="hive-am" width="180" />
+  <img src="web/public/logo-completo.png" alt="hive-am" width="100%" />
 </p>
 
-<h1 align="center">hive-am</h1>
-
 <p align="center">
   <strong>A colony of coding agents on your machine.</strong><br />
   Orchestrators and subagents over <b>Claude Code</b>, <b>OpenCode</b>, <b>Kiro</b> and <b>Cursor</b>, with the real sessions of each CLI, a browser UI and Telegram.
@@ -146,6 +144,8 @@ A step by step guide with screenshots, from installing hive-am to running resour
 
 Full documentation in English and Spanish: **[English](docs/reference/en/README.md)** · **[Español](docs/reference/es/README.md)**.
 
+Diagrams of how it works inside, with the file, function and line behind each step: **[English](docs/diagrams/en/README.md)** · **[Español](docs/diagrams/es/README.md)**.
+
 | Topic | Where |
 |---|---|
 | Overview and architecture | [docs/01](docs/reference/en/01-overview.md) |
@@ -166,3 +166,7 @@ Full documentation in English and Spanish: **[English](docs/reference/en/README.
 - A turn in flight during a crash is lost; the session is intact and the agent is idle on restart.
 - Instructions are advice to the model; what the server enforces is who an agent can delegate to, who a connection answers, which files can be sent, and the permission level.
 - There is no automated test suite. Features are checked with simulations against real agents (`server/scripts/sim-*.ts`).
+
+<p align="center">
+  <img src="web/public/logo.png" alt="hive-am" width="84" />
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hive-am",
-  "version": "1.11.0",
+  "version": "1.12.1",
   "description": "A colony of coding agents: orchestrators and subagents over Claude Code, OpenCode, Kiro and Cursor, with real session resume, a browser UI and Telegram.",
   "keywords": [
     "ai-agents",

package/server/dist/http/routes/fs.js

@@ -8,8 +8,9 @@ route('GET', '/api/fs/dirs', ({ url }) => {
     const p = resolve(url.searchParams.get('path') || homedir());
     if (!existsSync(p) || !statSync(p).isDirectory())
         throw bad('Not a folder');
-    // `files=yml,yaml` also lists the files with those extensions (to pick a file, e.g. a compose file).
-    const exts = (url.searchParams.get('files') ?? '').split(',').map((x) => x.trim().toLowerCase().replace(/^\./, '')).filter((x) => /^[a-z0-9]{1,8}$/.test(x));
+    // `files=yml,yaml` also lists the files with those extensions (to pick a file, e.g. a compose file). A name with no dot is its own
+    // extension, so `files=dockerfile,containerfile` lists `Dockerfile`, `Containerfile` and `web.Dockerfile`.
+    const exts = (url.searchParams.get('files') ?? '').split(',').map((x) => x.trim().toLowerCase().replace(/^\./, '')).filter((x) => /^[a-z0-9]{1,16}$/.test(x));
     let dirs = [], files = [];
     try {
         const all = readdirSync(p, { withFileTypes: true });

package/server/dist/http/routes/resources.js

@@ -1,9 +1,11 @@
 import { notifyAgentsChanged } from '../../runtime.js';
 import { DRIVER_PROPS } from '../../objects/driver-props.js';
-import { composeServices, listContainers, listImages } from '../../objects/docker-info.js';
+import { composeServices, inspectMachine, listContainers, listImages, listNetworks, listVolumes } from '../../objects/docker-info.js';
+import { buildImage, createMade, removeMade } from '../../objects/docker.js';
+import { copySource, readSource, writeSource } from '../../objects/files.js';
 import { agentObjectAction, agentObjectLogs, agentObjects } from '../../objects/agent.js';
 import { agentDb } from '../../objects/agent-db.js';
-import { dbColumnsOf, dbHistory, dbHistoryClear, dbRun, dbSavedAdd, dbSavedList, dbSavedRemove, dbSavedUpdate, dbSchemaOf, dbTestConfig, createObject, statsOf, httpDescribe, httpSession, httpSessionClear, httpSessionSet, httpInspect, httpExport, httpFileRead, httpFileWrite, httpFileCreate, httpRun, httpHistory, httpDocs, httpHistoryClear, httpScan, listObjects, setObjectManager, setAgentObjects, objectAction, objectServiceAction, listTemplates, createFromTemplate, objectInspect, objectLogs, removeObject, updateObject } from '../../objects/index.js';
+import { dbColumnsOf, dbHistory, dbHistoryClear, dbRun, dbSavedAdd, dbSavedList, dbSavedRemove, dbSavedUpdate, dbSchemaOf, dbTestConfig, createObject, statsOf, httpDescribe, httpSession, httpSessionClear, httpSessionSet, httpInspect, httpExport, httpFileRead, httpFileWrite, httpFileCreate, httpRun, httpHistory, httpDocs, httpHistoryClear, httpScan, listObjects, setObjectManager, setAgentObjects, objectAction, objectServiceAction, composeFileCopy, composeFileRead, composeFileWrite, objectApply, objectInspect, objectManagedCopy, objectPlan, objectInspectRaw, objectLogs, removeObject, updateObject } from '../../objects/index.js';
 import { body } from '../body.js';
 import { notFound } from '../errors.js';
 import { requireLocal } from '../guards.js';
@@ -28,18 +30,43 @@ write('POST', '/api/objects', (b) => createObject(b));
 write('PATCH', '/api/objects/:id', (b, { params }) => updateObject(params[0], b));
 route('DELETE', '/api/objects/:id', async ({ req, params }) => { local(req); if (!(await removeObject(params[0])))
     throw notFound('Object not found'); return { ok: true }; });
-route('GET', '/api/object-templates', () => listTemplates());
 write('PUT', '/api/objects/:id/manager', (b, { params }) => { const r = setObjectManager(params[0], b.agent_id); if (r.skillAdded)
     notifyAgentsChanged(); return r; });
 write('PUT', '/api/agents/:id/resources', (b, { params }) => { const r = setAgentObjects(params[0], b.object_ids); if (r.skillAdded)
     notifyAgentsChanged(); return r; });
-write('POST', '/api/objects/from-template', (b) => createFromTemplate(b));
+// Reads, open like the other reads of resources (the app is also reached by other names on the network). Secret-looking variables and the
+// passwords of URLs come hidden in the raw one unless `reveal=1`.
 route('GET', '/api/objects/:id/inspect', ({ params, url }) => objectInspect(params[0], p(url, 'service')));
+route('GET', '/api/objects/:id/inspect/raw', ({ params, url }) => objectInspectRaw(params[0], p(url, 'service'), url.searchParams.get('reveal') === '1'));
+// The whole `docker inspect` of anything on this machine (container, image, volume, network).
+route('GET', '/api/docker/inspect', ({ url }) => inspectMachine(url.searchParams.get('kind') ?? '', url.searchParams.get('ref') ?? '', url.searchParams.get('reveal') === '1'));
 write('POST', '/api/objects/:id/service', (b, { params }) => objectServiceAction(params[0], b.service, b.action));
 write('POST', '/api/objects/:id/action', (b, { params }) => objectAction(params[0], b.action));
-// What Docker knows, to suggest in the forms (containers, images, the services of a compose file).
+// Changing a container hive-am created (local app only): what applying the settings in the form would do (Docker only read), then applying
+// the saved ones (recreating needs `confirm: true`). An existing container is never changed: it is read to fill the form of a managed copy.
+write('POST', '/api/objects/:id/docker/plan', (b, { params }) => objectPlan(params[0], b.config));
+write('POST', '/api/objects/:id/docker/apply', (b, { params }) => objectApply(params[0], b));
+guarded('/api/objects/:id/docker/managed-copy', ({ params }) => objectManagedCopy(params[0]));
+// What Docker knows, to suggest in the forms (containers, images, volumes, networks, the services of a compose file).
 route('GET', '/api/docker/containers', () => listContainers());
 route('GET', '/api/docker/images', () => listImages());
+route('GET', '/api/docker/volumes', () => listVolumes());
+route('GET', '/api/docker/networks', () => listNetworks());
+// What the Docker form creates when asked (local app only): a network, a volume, an image from a Dockerfile. A network or a volume is
+// removed only if hive-am created it and no container uses it (checked in objects/docker.ts, against Docker).
+write('POST', '/api/docker/networks', (b) => createMade('network', b.name));
+write('POST', '/api/docker/volumes', (b) => createMade('volume', b.name));
+guarded('/api/docker/networks/:name', ({ params }) => removeMade('network', params[0]), 'DELETE');
+guarded('/api/docker/volumes/:name', ({ params }) => removeMade('volume', params[0]), 'DELETE');
+write('POST', '/api/docker/images/build', (b) => buildImage(b));
+// Editing the compose file of a resource (its path is the saved one) and a Dockerfile (path from the page, checked by name in objects/files.ts),
+// in place or as a copy next to it. They are the person's own files, which may hold secrets: local app only, reading included. A stale etag is 409.
+guarded('/api/objects/:id/docker/file', ({ params }) => composeFileRead(params[0]));
+write('PUT', '/api/objects/:id/docker/file', (b, { params }) => composeFileWrite(params[0], b.content, b.etag));
+write('POST', '/api/objects/:id/docker/file/copy', (b, { params }) => composeFileCopy(params[0], b));
+guarded('/api/docker/dockerfile', ({ url }) => readSource('dockerfile', url.searchParams.get('path') ?? ''));
+write('PUT', '/api/docker/dockerfile', (b) => writeSource('dockerfile', b.path, b.content, b.etag));
+write('POST', '/api/docker/dockerfile/copy', (b) => copySource('dockerfile', b.path, b.name, b.content, b.overwrite === true));
 route('GET', '/api/docker/compose-services', ({ url }) => composeServices(url.searchParams.get('file') ?? ''));
 route('GET', '/api/objects/:id/stats', ({ params }) => statsOf(params[0]));
 route('GET', '/api/objects/:id/http', ({ params }) => httpScan(params[0]));

package/server/dist/objects/docker-info.js

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { basename, dirname } from 'node:path';
 import { execCapture } from './exec.js';
-import { ObjectError } from './model.js';
+import { CONTAINER, IMAGE, ObjectError } from './model.js';
 /**
- * What Docker knows, to suggest in the forms: the containers on this machine, the images, and the services of a compose file. Read-only;
- * when Docker is not available the lists are empty and say why.
+ * What Docker knows, to suggest in the forms: the containers on this machine, the images, volumes and networks (each with how many
+ * containers use it), and the services of a compose file. Read-only; when Docker is not available the lists are empty and say why.
  */
 const run = async (args, o = {}) => {
     const r = await execCapture('docker', args, { cwd: o.cwd, timeout: o.timeout ?? 15_000, env: { ...process.env, DOCKER_CLI_HINTS: 'false' } });
@@ -16,20 +16,81 @@ const lines = (out) => out.trim().split('\n').flatMap((l) => { try {
 catch {
     return [];
 } });
-export async function listContainers() {
-    const r = await run(['ps', '-a', '--format', '{{json .}}']);
+/** Docker is installed but its daemon does not answer (stopped, or no permission on its socket). */
+export const NO_DAEMON = /Cannot connect to the Docker daemon|Is the docker daemon running|error during connect|permission denied while trying to connect/i;
+/** Variable names whose value is hidden unless asked for (the same pattern the interface uses for the variables it shows). */
+export const SECRET_NAME = /pass|secret|token|api[_-]?key|auth|credential|private/i;
+export const MASK = '••••••••';
+/** The password of a URL with credentials (`scheme://user:password@host`), wherever it sits in a value. */
+const URL_PASSWORD = /([a-z][a-z0-9+.-]*:\/\/[^\s/:@]*:)[^\s/@]+@/gi;
+/** A `NAME=value` variable with its secret hidden: the whole value when the name looks like a secret, else the password of any URL in it. */
+export function maskVar(item) {
+    const i = item.indexOf('=');
+    if (i < 0)
+        return item;
+    if (SECRET_NAME.test(item.slice(0, i)))
+        return `${item.slice(0, i + 1)}${MASK}`;
+    return item.slice(0, i + 1) + item.slice(i + 1).replace(URL_PASSWORD, `$1${MASK}@`);
+}
+const failed = (r) => r.err.trim().split('\n').pop()?.slice(0, 200);
+const list = (v) => String(v ?? '').split(',').map((x) => x.trim()).filter(Boolean);
+const labelled = (labels, re) => re.test(String(labels ?? ''));
+/** One label of `docker ps` (`k=v,k=v`); a value with a comma is cut there, which these labels (ids and names) never have. */
+const label = (labels, key) => new RegExp(`(?:^|,)${key.replace(/\./g, '\\.')}=([^,]*)`).exec(String(labels ?? ''))?.[1] || undefined;
+const BUILTIN = ['bridge', 'host', 'none'];
+let reading = null;
+/**
+ * The containers of this machine. The form asks for containers, images, volumes and networks at once, and the last three count who uses
+ * them: while one `docker ps` is running, every other caller gets its answer instead of starting another one.
+ */
+export function listContainers() {
+    reading ??= readContainers().finally(() => { reading = null; });
+    return reading;
+}
+async function readContainers() {
+    // --no-trunc: without it Docker cuts the mounts to a few characters ("/home/you/Doc…").
+    const r = await run(['ps', '-a', '--no-trunc', '--format', '{{json .}}']);
     if (r.code !== 0)
-        return { available: false, error: r.err.trim().split('\n').pop()?.slice(0, 200), containers: [] };
-    const containers = lines(r.out).map((j) => ({ id: String(j.ID), name: String(j.Names), image: String(j.Image), state: String(j.State), status: String(j.Status), ports: String(j.Ports ?? ''), managed: /(^|,)hive-am\.object=/.test(String(j.Labels ?? '')) }));
-    return { available: true, containers: containers.sort((a, b) => a.name.localeCompare(b.name)) };
+        return { available: false, error: failed(r), containers: [] };
+    const all = lines(r.out).map((j) => ({
+        id: String(j.ID).slice(0, 12), name: String(j.Names), image: String(j.Image), state: String(j.State), status: String(j.Status), ports: String(j.Ports ?? ''),
+        managed: labelled(j.Labels, /(^|,)hive-am\.object=/), mounts: list(j.Mounts), networks: list(j.Networks),
+        object: label(j.Labels, 'hive-am.object'), project: label(j.Labels, 'com.docker.compose.project'), service: label(j.Labels, 'com.docker.compose.service'),
+    }));
+    return { available: true, containers: all.sort((a, b) => a.name.localeCompare(b.name)) };
 }
+/** `nginx` and `nginx:latest` are the same image for counting who uses it. */
+const sameImage = (ref, image) => ref === image || ref === `${image}:latest`;
 export async function listImages() {
-    const r = await run(['images', '--format', '{{json .}}']);
+    const [r, c] = await Promise.all([run(['images', '--format', '{{json .}}']), listContainers()]);
     if (r.code !== 0)
-        return { available: false, error: r.err.trim().split('\n').pop()?.slice(0, 200), images: [] };
-    const images = lines(r.out).filter((j) => j.Repository && j.Repository !== '<none>').map((j) => ({ ref: j.Tag && j.Tag !== '<none>' ? `${j.Repository}:${j.Tag}` : String(j.Repository), id: String(j.ID), size: String(j.Size ?? ''), created: String(j.CreatedSince ?? '') }));
+        return { available: false, error: failed(r), images: [] };
+    const images = lines(r.out).filter((j) => j.Repository && j.Repository !== '<none>').map((j) => {
+        const ref = j.Tag && j.Tag !== '<none>' ? `${j.Repository}:${j.Tag}` : String(j.Repository);
+        return { ref, id: String(j.ID), size: String(j.Size ?? ''), created: String(j.CreatedSince ?? ''), inUse: c.containers.filter((x) => sameImage(ref, x.image)).length };
+    });
     return { available: true, images: [...new Map(images.map((i) => [i.ref, i])).values()].sort((a, b) => a.ref.localeCompare(b.ref)) };
 }
+export async function listVolumes() {
+    const [r, c] = await Promise.all([run(['volume', 'ls', '--format', '{{json .}}']), listContainers()]);
+    if (r.code !== 0)
+        return { available: false, error: failed(r), volumes: [] };
+    const volumes = lines(r.out).map((j) => {
+        const name = String(j.Name);
+        return { name, driver: String(j.Driver ?? ''), anonymous: /^[0-9a-f]{64}$/.test(name) || labelled(j.Labels, /(^|,)com\.docker\.volume\.anonymous=/), managed: labelled(j.Labels, /(^|,)hive-am\.created=1(,|$)/), inUse: c.containers.filter((x) => x.mounts.includes(name)).length };
+    });
+    return { available: true, volumes: volumes.sort((a, b) => Number(a.anonymous) - Number(b.anonymous) || a.name.localeCompare(b.name)) };
+}
+export async function listNetworks() {
+    const [r, c] = await Promise.all([run(['network', 'ls', '--format', '{{json .}}']), listContainers()]);
+    if (r.code !== 0)
+        return { available: false, error: failed(r), networks: [] };
+    const networks = lines(r.out).map((j) => {
+        const name = String(j.Name);
+        return { name, id: String(j.ID), driver: String(j.Driver ?? ''), scope: String(j.Scope ?? ''), builtin: BUILTIN.includes(name), managed: labelled(j.Labels, /(^|,)hive-am\.created=1(,|$)/), inUse: c.containers.filter((x) => x.networks.includes(name)).length };
+    });
+    return { available: true, networks: networks.sort((a, b) => Number(b.builtin) - Number(a.builtin) || a.name.localeCompare(b.name)) };
+}
 /** Without Docker's help: the keys under a top-level `services:` (enough for ordinary compose files). */
 function servicesByHand(text) {
     const out = [];
@@ -73,3 +134,49 @@ export async function composeServices(file) {
     catch { /* unreadable */ }
     return { services: servicesByHand(text).sort(), project, source: 'file', error: r.err.trim().split('\n').pop()?.slice(0, 200) };
 }
+const KINDS = ['container', 'image', 'volume', 'network'];
+/** The `NAME=value` items of `Config.Env` (and the older `ContainerConfig.Env` of an image) with their secrets hidden (`maskVar`). */
+function maskEnv(items) {
+    let n = 0;
+    for (const it of items)
+        for (const cfg of [it?.Config, it?.ContainerConfig]) {
+            if (!Array.isArray(cfg?.Env))
+                continue;
+            cfg.Env = cfg.Env.map((e) => {
+                const s = String(e), m = maskVar(s);
+                if (m === s)
+                    return e;
+                n++;
+                return m;
+            });
+        }
+    return n;
+}
+/**
+ * The whole `docker inspect` of a container, an image, a volume or a network, as indented JSON. The values of the variables whose name
+ * looks like a secret, and the passwords of URLs in the others, are hidden unless `reveal` (other fields, like labels or the command, can
+ * carry secrets too and are not touched).
+ * `available: false` when Docker is not installed or does not answer.
+ */
+export async function inspectMachine(kind, ref, reveal = false) {
+    if (!KINDS.includes(kind))
+        throw new ObjectError('Say what to inspect: a container, an image, a volume or a network');
+    if (!(kind === 'image' ? IMAGE : CONTAINER).test(ref))
+        throw new ObjectError(`That is not a valid ${kind} name`);
+    const r = await run([kind, 'inspect', ref], { timeout: 20_000 });
+    if (r.code !== 0) {
+        const error = r.err.trim().split('\n').pop()?.slice(0, 200) || `docker exited with ${r.code}`;
+        if (/not installed/.test(r.err) || NO_DAEMON.test(r.err))
+            return { available: false, error, text: '', masked: 0 };
+        throw new ObjectError(`Docker has no ${kind} ${ref}`);
+    }
+    let items;
+    try {
+        items = JSON.parse(r.out);
+    }
+    catch {
+        throw new ObjectError(`docker ${kind} inspect did not return JSON`);
+    }
+    const masked = reveal ? 0 : maskEnv(items);
+    return { available: true, text: JSON.stringify(items, null, 2), masked };
+}