Read the machine, not the notes: status, and an export that survives them

The state file is intent -- what this installer wrote down that it did. The
machine is reality. They part company more often than is comfortable: a
container stopped by hand, a deployment copied from somewhere else, an
installation made by an older version, a service removed with the runtime
directly. Reporting either one as though it were the other is worse than
reporting nothing, because the operator believes it.

So there are two readings now, shown side by side.

  inbuxa status    what is installed, what is running, where they disagree

It exits non-zero when they disagree, so a machine can be asked in a script
whether it still matches itself.

And export no longer replays the state file. It reads the deployment --
which services the compose file declares, which are up, the mail host
written into the server's hostname and the domain under it -- and uses
intent only for the shapes, which the machine cannot tell you. A deployment
with no state file at all still describes itself, which matters because that
is exactly the machine someone wants to draw: the one that was set up before
any of this existed.

Sixteen checks, on Debian 13 and Rocky 9, including the two that are the
point: a webmail stopped by hand is reported stopped and called out, and a
deployment with the state file deleted still exports a file that plan reads
back and finds nothing to do about.

README.md

@@ -49,6 +49,10 @@ This is early. What is built:
   diffs the file against what is actually installed here and changes
   nothing; `apply` converges to it, adding and removing components;
   `export` writes the file from what is already here.
+- **`status`** -- what is installed, what is running, and where those two
+  disagree: a container stopped by hand, or a deployment nothing recorded
+  installing. It exits non-zero when they disagree, so a machine can be
+  asked in a script whether it still matches itself.
 
 Not built yet: host installs, the terminal interface, `join`, `status`,
 `upgrade`, `uninstall`. The design is in the inbuxa specification (§6.1 and
@@ -76,6 +80,7 @@ is tested on a throwaway virtual machine rather than on anybody's desk:
     e2e/vm/run.sh e2e/cases/install-local.sh   a whole suite, and signing in to it
     e2e/vm/run.sh e2e/cases/install-public.sh  the same with real ports and certificates
     e2e/vm/run.sh e2e/cases/topology.sh       growing and shrinking from a file
+    e2e/vm/run.sh e2e/cases/status-export.sh  intent against reality, and the file
     e2e/vm/down.sh                            remove it
 
 Each case starts from a copy of the machine taken when it was new, so a run

cmd/inbuxa/main.go

@@ -21,6 +21,7 @@ import (
 
 	"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/apply"
 	"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/deps"
+	"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/discover"
 	"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/host"
 	"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/plan"
 	"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/state"
@@ -38,6 +39,7 @@ const usage = `inbuxa -- install the inbuxa suite on this machine
   inbuxa deps [--install]    what is missing for a shape, and fix it
   inbuxa plan -f FILE        what a topology file would change here
   inbuxa apply -f FILE       make this machine match that file
+  inbuxa status              what is installed here, and whether it agrees
   inbuxa export [-o FILE]    write a topology file from what is here
   inbuxa version             this program's version
 
@@ -101,6 +103,8 @@ func main() {
 		os.Exit(topologyCmd(os.Args[2:], true))
 	case "export":
 		os.Exit(exportCmd(os.Args[2:]))
+	case "status":
+		os.Exit(statusCmd())
 	case "version":
 		fmt.Println(version)
 	case "-h", "--help", "help":
@@ -395,26 +399,51 @@ func exportCmd(args []string) int {
 	if err := fs.Parse(args); err != nil {
 		return 2
 	}
+	ctx := context.Background()
 	st, err := state.Load()
 	if err != nil {
 		fmt.Fprintln(os.Stderr, err.Error())
 		return 1
 	}
-	if !st.Installed() {
+	f := host.Survey(ctx)
+	found := discover.Run(ctx, f)
+
+	if !st.Installed() && found.Dir == "" {
 		fmt.Fprintln(os.Stderr, "nothing is installed here, so there is nothing to describe")
 		return 1
 	}
+
 	name := st.Machine
 	if name == "" {
 		name, _ = os.Hostname()
 	}
-	m := topology.Machine{Name: name, Dir: st.Dir}
+	dir, domain := st.Dir, st.Domain
+	if dir == "" {
+		dir = found.Dir
+	}
+	if domain == "" {
+		domain = found.Domain
+	}
+
+	// Intent first, because it knows the shapes; reality for anything intent
+	// does not mention, so a deployment made by an older version or by hand
+	// still describes itself.
+	m := topology.Machine{Name: name, Dir: dir}
 	for _, kind := range []string{"server", "console", "webmail"} {
-		if sh, ok := st.Shapes[kind]; ok {
+		switch {
-			m.Components = append(m.Components, topology.Component{Kind: kind, Shape: sh})
+		case st.Shapes[kind] != "":
+			m.Components = append(m.Components, topology.Component{Kind: kind, Shape: st.Shapes[kind]})
+		case found.Services[kind] != "":
+			m.Components = append(m.Components, topology.Component{Kind: kind, Shape: "container"})
 		}
 	}
-	t := &topology.Topology{Version: topology.Version, Domain: st.Domain, Machines: []topology.Machine{m}}
+	if !found.Proxy && found.Dir != "" {
+		m.Proxy = "none"
+	}
+	t := &topology.Topology{Version: topology.Version, Domain: domain, Machines: []topology.Machine{m}}
+	if found.MailHost != "" {
+		t.MailHost = found.MailHost
+	}
 	t.Defaults()
 	if err := t.Validate(); err != nil {
 		fmt.Fprintln(os.Stderr, "what is installed here does not describe a whole installation: "+err.Error())
@@ -434,6 +463,72 @@ func exportCmd(args []string) int {
 	return 0
 }
 
+// statusCmd is the same reading as export, shown to a person: what is
+// installed, what is running, and where the two disagree.
+func statusCmd() int {
+	ctx := context.Background()
+	st, err := state.Load()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err.Error())
+		return 1
+	}
+	f := host.Survey(ctx)
+	found := discover.Run(ctx, f)
+
+	if !st.Installed() && found.Dir == "" {
+		fmt.Println("Nothing is installed on this machine.")
+		return 0
+	}
+
+	name := st.Machine
+	if name == "" {
+		name, _ = os.Hostname()
+	}
+	fmt.Printf("This machine is %q", name)
+	if st.Topology != "" {
+		fmt.Printf(", from %s", st.Topology)
+	}
+	fmt.Println()
+	if found.Dir != "" {
+		fmt.Printf("  %-14s %s\n", "deployment", found.Dir)
+	}
+	if found.Domain != "" || st.Domain != "" {
+		domain := st.Domain
+		if domain == "" {
+			domain = found.Domain
+		}
+		fmt.Printf("  %-14s %s\n", "domain", domain)
+	}
+	if found.Runtime != "" {
+		fmt.Printf("  %-14s %s\n", "runtime", found.Runtime)
+	}
+
+	fmt.Println("\nComponents")
+	for _, kind := range []string{"server", "console", "webmail"} {
+		shape, intended := st.Shapes[kind]
+		state, present := found.Services[kind]
+		switch {
+		case !intended && !present:
+			continue
+		case intended && present:
+			fmt.Printf("  %-8s installed as a %-9s %s\n", kind, shape, state)
+		case intended:
+			fmt.Printf("  %-8s installed as a %-9s missing from the deployment\n", kind, shape)
+		default:
+			fmt.Printf("  %-8s %-24s %s\n", kind, "in the deployment", state)
+		}
+	}
+
+	if d := discover.Drift(st.Shapes, found); len(d) > 0 {
+		fmt.Println("\nWorth a look")
+		for _, line := range d {
+			fmt.Printf("  - %s\n", line)
+		}
+		return 1
+	}
+	return 0
+}
+
 func machineNames(t *topology.Topology) []string {
 	var out []string
 	for _, m := range t.Machines {

e2e/cases/status-export.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: 2026 Coffey Labs
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# What is here, as against what we wrote down that we did.
+#
+# The interesting cases are the ones where those two part company: a
+# container stopped by hand, and a deployment with no state file at all --
+# installed by an older version, or copied from another machine. An installer
+# that reports intent as though it were reality is worse than one that
+# reports nothing, because the operator believes it.
+#
+# The export has to survive both, because a design that starts from a file
+# that does not describe the machine is a design of somewhere else.
+#
+# Run from the host with: e2e/vm/run.sh e2e/cases/status-export.sh
+set -uo pipefail
+
+pass=0; fail=0
+ok()   { echo "  ok   $*"; pass=$((pass+1)); }
+bad()  { echo "  FAIL $*"; fail=$((fail+1)); }
+has()  { grep -q -- "$2" <<<"$1" && ok "$3" || { bad "$3"; echo "$1" | sed 's/^/    /'; }; }
+
+DIR=/var/lib/inbuxa
+rt() { command -v docker >/dev/null 2>&1 && echo docker || echo podman; }
+compose() {
+  if [ "$(rt)" = docker ]; then
+    docker compose -f "$DIR/compose.yaml" "$@"
+  else
+    DOCKER_HOST=unix:///run/podman/podman.sock \
+      /usr/local/lib/docker/cli-plugins/docker-compose -f "$DIR/compose.yaml" "$@"
+  fi
+}
+
+echo "==> before anything is installed"
+OUT="$(/tmp/inbuxa status 2>&1)"; rc=$?
+has "$OUT" "Nothing is installed" "status says so"
+[ $rc -eq 0 ] && ok "and that is not an error" || bad "exit $rc"
+OUT="$(/tmp/inbuxa export 2>&1)"; rc=$?
+[ $rc -ne 0 ] && ok "export refuses (exit $rc)" || bad "export invented something"
+
+echo
+echo "==> install, then ask what is here"
+/tmp/inbuxa install --local --domain example.test --install-deps --yes >/tmp/install.log 2>&1 || { bad "install failed"; tail -5 /tmp/install.log | sed 's/^/    /'; }
+OUT="$(/tmp/inbuxa status 2>&1)"; rc=$?
+echo "$OUT" | sed 's/^/    /'
+[ $rc -eq 0 ] && ok "status is clean (exit 0)" || bad "exit $rc"
+has "$OUT" "server   installed as a container running" "the server is installed and running"
+has "$OUT" "webmail  installed as a container running" "so is the webmail"
+has "$OUT" "example.test" "and it knows the domain"
+
+echo
+echo "==> a container stopped by hand"
+compose stop webmail >/dev/null 2>&1
+OUT="$(/tmp/inbuxa status 2>&1)"; rc=$?
+has "$OUT" "webmail  installed as a container stopped" "status shows it stopped"
+has "$OUT" "webmail is installed and not running" "and calls it out"
+[ $rc -ne 0 ] && ok "and says so in its exit code ($rc)" || bad "a machine that disagrees with itself exited 0"
+compose start webmail >/dev/null 2>&1
+
+echo
+echo "==> export describes this machine"
+/tmp/inbuxa export -o /tmp/exported.json >/dev/null 2>&1 || bad "export failed"
+python3 - <<'PY'
+import json
+t = json.load(open('/tmp/exported.json'))
+m = t['machines'][0]
+kinds = sorted(c['kind'] for c in m['components'])
+print(f"    domain={t['domain']} machines={len(t['machines'])} components={','.join(kinds)} proxy={m.get('proxy','')}")
+assert t['domain'] == 'example.test', t['domain']
+assert kinds == ['console', 'server', 'webmail'], kinds
+PY
+[ $? -eq 0 ] && ok "the file says what is here" || bad "the exported file is wrong"
+
+echo
+echo "==> and the file it wrote is one it accepts back"
+OUT="$(/tmp/inbuxa plan -f /tmp/exported.json 2>&1)"; rc=$?
+[ $rc -eq 0 ] && ok "plan reads it (exit 0)" || { bad "exit $rc"; echo "$OUT" | sed 's/^/    /'; }
+has "$OUT" "nothing to do" "and finds nothing to do, which is the point"
+
+echo
+echo "==> a deployment nobody wrote down: the state file removed"
+cp /etc/inbuxa/install.json /tmp/state.json.bak
+rm -f /etc/inbuxa/install.json
+OUT="$(/tmp/inbuxa status 2>&1)"
+echo "$OUT" | sed 's/^/    /'
+has "$OUT" "in the deployment" "status describes it from the deployment itself"
+has "$OUT" "nothing recorded installing it" "and says nothing recorded it"
+/tmp/inbuxa export -o /tmp/exported2.json >/dev/null 2>&1 || bad "export failed without state"
+python3 - <<'PY'
+import json
+t = json.load(open('/tmp/exported2.json'))
+kinds = sorted(c['kind'] for c in t['machines'][0]['components'])
+print(f"    rebuilt from the deployment: domain={t['domain']} components={','.join(kinds)}")
+assert t['domain'] == 'example.test', t['domain']
+assert kinds == ['console', 'server', 'webmail'], kinds
+PY
+[ $? -eq 0 ] && ok "export rebuilds the file from the deployment" || bad "export could not describe an unrecorded deployment"
+cp /tmp/state.json.bak /etc/inbuxa/install.json
+
+echo
+echo "==> $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

internal/discover/discover.go

@@ -0,0 +1,140 @@
+// SPDX-FileCopyrightText: 2026 Coffey Labs
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// Package discover reads what is actually on this machine, as opposed to
+// what the installer wrote down that it did.
+//
+// The two are not the same thing, and the difference is the useful part. A
+// container stopped by hand, a deployment directory copied from another
+// machine, an installation made by an older version of this program, or a
+// service someone removed with the runtime directly: in each case intent and
+// reality have parted company, and an operator wants to be told, not to have
+// one quietly reported as the other.
+//
+// So: state is intent, this is reality, and the two are shown side by side.
+package discover
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/docker"
+	"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/host"
+)
+
+// Found is what this machine turns out to be running.
+type Found struct {
+	Dir        string            // the deployment directory, when there is one
+	Domain     string            // read back from the deployment
+	MailHost   string            //
+	Services   map[string]string // component -> running|stopped|absent
+	Compose    []string          // services the compose file declares
+	Runtime    string            // what is running them
+	Proxy      bool              // the deployment includes a proxy
+	Credential bool              // credentials.txt is there
+}
+
+// Dirs are where a deployment may be. The first is what this installer
+// writes; the second is oneshot's habit, and someone moving across will have
+// one.
+var Dirs = []string{"/var/lib/inbuxa", "/opt/inbuxa"}
+
+var serviceLine = regexp.MustCompile(`(?m)^  ([a-z][a-z0-9_-]*):\s*$`)
+var hostnameLine = regexp.MustCompile(`(?m)^\s+hostname:\s*(\S+)\s*$`)
+
+// Run looks for a deployment and reports what it finds. It never changes
+// anything, and a machine with nothing on it is not an error.
+func Run(ctx context.Context, f host.Facts, dirs ...string) Found {
+	found := Found{Services: map[string]string{}, Runtime: f.Runtime.Kind}
+	if len(dirs) == 0 {
+		dirs = Dirs
+	}
+	for _, dir := range dirs {
+		if _, err := os.Stat(filepath.Join(dir, "compose.yaml")); err == nil {
+			found.Dir = dir
+			break
+		}
+	}
+	if found.Dir == "" {
+		return found
+	}
+
+	if _, err := os.Stat(filepath.Join(found.Dir, "credentials.txt")); err == nil {
+		found.Credential = true
+	}
+
+	b, err := os.ReadFile(filepath.Join(found.Dir, "compose.yaml"))
+	if err != nil {
+		return found
+	}
+	text := string(b)
+	for _, m := range serviceLine.FindAllStringSubmatch(text, -1) {
+		name := m[1]
+		if name == "caddy" {
+			found.Proxy = true
+			continue
+		}
+		if name == "server" || name == "console" || name == "webmail" {
+			found.Compose = append(found.Compose, name)
+			found.Services[name] = "stopped"
+		}
+	}
+	// The mail host is written into the server's hostname, and the domain
+	// follows from it. Read back rather than assumed, because this may be a
+	// deployment this program did not write.
+	if m := hostnameLine.FindStringSubmatch(text); m != nil {
+		found.MailHost = m[1]
+		if _, rest, ok := strings.Cut(m[1], "."); ok {
+			found.Domain = rest
+		}
+	}
+
+	// What is actually up. A compose file that lists a service proves
+	// nothing about whether it is running.
+	if f.Runtime.Usable {
+		docker.UseRuntime(f.Runtime)
+		cmp := docker.Compose{Dir: found.Dir, Runtime: f.Runtime}
+		for _, name := range found.Compose {
+			if cmp.Running(ctx, name) {
+				found.Services[name] = "running"
+			}
+		}
+	}
+	return found
+}
+
+// Components is what a topology file would say this machine runs. Everything
+// the deployment declares counts, running or not: a stopped webmail is still
+// installed here, and a file that left it out would be asking for it to be
+// removed.
+func (f Found) Components() []string {
+	var out []string
+	for _, name := range []string{"server", "console", "webmail"} {
+		if _, ok := f.Services[name]; ok {
+			out = append(out, name)
+		}
+	}
+	return out
+}
+
+// Drift is where intent and reality disagree, in sentences fit to show
+// someone. Empty means they agree.
+func Drift(shapes map[string]string, f Found) []string {
+	var out []string
+	for _, kind := range []string{"server", "console", "webmail"} {
+		_, intended := shapes[kind]
+		state, present := f.Services[kind]
+		switch {
+		case intended && !present:
+			out = append(out, kind+" was installed here, and the deployment no longer has it")
+		case !intended && present:
+			out = append(out, kind+" is in the deployment, and nothing recorded installing it")
+		case intended && present && state != "running":
+			out = append(out, kind+" is installed and not running")
+		}
+	}
+	return out
+}