Service Control

mac pull, mac build, mac start, mac stop, mac restart, mac status, mac logs, mac info, mac test, and mac clean.

`mac pull`

Pull container images from the configured registry. Mode is required.

~$ mac pull all       # All images (master + agent)
~$ mac pull master    # Master images only
~$ mac pull agent     # Agent images only

Images are version-pinned to match the package version (see /usr/share/mango-ai-center/VERSION). Set MAC_REGISTRY to use a private mirror — see Environment.

With --local (or MAC_IMAGE_SOURCE=local), mac pull builds the MAC images from source instead and only pulls the external image-only services (Prometheus, Loki, GPU vendor exporters, mango-sdk-agent).

`mac build`

Build MAC images locally from a source checkout. Mode is required.

~$ mac build all       # Build master + agent images
~$ mac build master    # Master images only
~$ mac build agent     # Agent images only

The built images are tagged identically to the registry references, so mac start <mode> --local runs exactly what was built. Unlike mac pull --local, this does not fetch external image-only services. Requires MAC_CONFIG_DIR to point at the checkout's deploy/ directory — see Without the Package.

`mac start`

Start MAC services. Mode is required.

~$ mac start all       # Master + Agent on this host
~$ mac start master    # Master only (web UI, API, Prometheus)
~$ mac start agent     # Agent only (exporters, sdk-agent, bmc-agent)

mac start pulls any missing images, brings up the compose project in detached mode, and prints the access URLs. The agent mode also registers this host with the master at MASTER_IP — on multi-homed hosts the CLI asks the kernel's routing table which local address reaches the master and registers that one.

Flags:

--local — build images from source and run them (MAC_IMAGE_SOURCE=local)
--registry — force published images (the default)

~$ mac start master --local    # Build + run local master images

`mac stop`

Stop the running services. Mode is required.

~$ mac stop all
~$ mac stop master
~$ mac stop agent

mac stop agent notifies the master so the node is deregistered from the inventory. This is the right command to use when you are retiring a server. For a temporary outage (reboot, maintenance window), it is fine to just power-cycle the host — agents that simply go offline remain registered, so your inventory survives.

`mac restart`

Convenience wrapper for mac stop <mode> followed by mac start <mode>. Mode is required.

~$ mac restart all
~$ mac restart master
~$ mac restart agent
~$ mac restart master --local   # restart onto locally-built images

Use this after editing variables with mac env set so the new values reach the containers. The --local / --registry flags are forwarded to the start step.

`mac status`

Lists every MAC container on this host with its status and published ports.

`mac logs`

Show container logs without remembering the exact docker-compose invocation.

~$ mac logs                    # last 20 lines from every MAC container
~$ mac logs api-server         # last 100 lines from one service
~$ mac logs api-server -f      # follow one service (--follow also works)

`mac info`

Prints a single-screen summary of the local installation: CLI version, hostname, OS and kernel, Docker / Docker Compose versions, config directory, and the GPU profile detected on this host — nvidia, amd, nvidia, amd (both vendors present), or none detected. Use it as the first diagnostic when a node is behaving unexpectedly.

`mac test`

Run MAC operator tests against an already-running stack. mac test only inspects a running deployment — start it first with mac start. test is an umbrella command; sanity is its only subcommand today and the default, so mac test and mac test sanity are equivalent:

~$ mac test           # run the sanity test (default)
~$ mac test sanity    # the same thing, spelled out

On an all-in-one deployment (mac start all — master and agent on the same host), the sanity test checks the health of every MAC service on that node in one pass, plus core cluster API checks (agent registry, alert rules, Prometheus reachability). It prints a per-node [PASS]/[FAIL]/[SKIP] table and a summary line. Just run it on the node — no login and no MASTER_IP are required, since the master is local.

Sample output on a healthy all-in-one node:

~$ mac test
Mango AI Center — Cluster Sanity Test
========================================
Node: gpu-server-01 (10.1.5.7)
  [PASS] api-server         (docker_health: healthy)
  [PASS] bmc-agent          (docker_health: healthy)
  [SKIP] loki               (skip: no healthcheck declared (by design))
  [PASS] mango-sdk-agent    (docker_health: healthy)
  [PASS] metrics-bridge     (docker_health: healthy)
  [PASS] nic-exporter       (docker_health: healthy)
  [PASS] prometheus         (docker_health: healthy)
  [PASS] rocm-exporter      (running_only: running)
  [PASS] sw-exporter        (docker_health: healthy)
  [PASS] switch-exporter    (docker_health: healthy)
  [PASS] sys-exporter       (docker_health: healthy)
  [PASS] sys-manager        (docker_health: healthy)
  [PASS] web-ui             (docker_health: healthy)
Cluster API checks:
  [PASS] GET /api/v1/agents (1 agents registered)
  [PASS] GET /api/v1/alert-rules (15 rules configured)
  [PASS] GET /api/v1/alert-rules/defaults (15 default rules)
  [PASS] Prometheus reachable
========================================
RESULT: ALL PASSED (1 nodes, 17 checks)

An all-in-one node runs the master services (api-server, web-ui, metrics-bridge, prometheus, loki, switch-exporter) and the agent services (sys-exporter, bmc-agent, nic-exporter, sw-exporter, mango-sdk-agent, and the GPU exporter for this host — rocm-exporter on AMD, dcgm-exporter on NVIDIA), plus sys-manager, which runs on every node, side by side — so all of them appear under the one node. Services are listed alphabetically. The node registers itself as its own agent, which is why the agent count is 1.

Reading the table:

[PASS] — the service is healthy (docker_health: healthy), or, for third-party images with no Docker healthcheck (e.g. the GPU vendor exporters), simply running (running_only: running).
[SKIP] — a service that intentionally ships without a healthcheck (e.g. loki). A skip is not a failure; it is reported for transparency.
[FAIL] — the service is missing, stopped, or unhealthy. Any [FAIL] fails the whole run and is named in the summary line, e.g.:
```
RESULT: 1 FAILED — gpu-server-01: rocm-exporter
```

If the stack isn't running yet — or the local api-server hasn't come up — the command says so and exits 2. This is distinct from a health failure and should not be read as one; start the stack with mac start all first, then re-run mac test:

~$ mac test
Error: could not reach the MAC master at http://localhost:28080/api/v1/cluster/sanity-check: dial tcp [::1]:28080: connect: connection refused

'mac test sanity' aggregates results from the master node's cluster-wide
view. Run it on the master node, or point it at the master explicitly:
  mac env set MASTER_IP=<master-ip>   (and MASTER_API_PORT if non-default)

Exit codes (script-friendly):

Code	Meaning
`0`	All checks passed
`1`	One or more checks failed
`2`	Could not reach the master

`mac version`

~$ mac version       # or: mac -v / mac --version

Prints just the CLI version and exits — useful in scripts that gate on the installed MAC version.

`mac clean`

Removes everything: containers, the MAC docker network, named volumes (including the Prometheus time-series database and Loki logs), and the locally cached MAC images. Use this to start completely fresh.

~$ mac clean

warning

mac clean is destructive and cannot be undone. Back up Prometheus volumes first if you want to preserve historical metrics.

mac pull​

mac build​

mac start​

mac stop​

mac restart​

mac status​

mac logs​

mac info​

mac test​

mac version​

mac clean​