Skip to main content

Installation & Startup

Start with mac status -v, mac env, and mac images --check.

mac command not found after dpkg -i​

Run hash -r or open a new shell. If a MAC stack ran before the package was installed, /usr/bin/mac may be a directory. The package removes it when it is empty; otherwise inspect and remove it, then reinstall the package.

mac start fails with "permission denied" on /var/run/docker.sock​

Add yourself to the docker group, then re-login if needed. Some commands still need sudo; see Run mac Without sudo.

sudo usermod -aG docker "$USER"
newgrp docker

mac start fails with "port is already allocated" after a reboot​

Leftover docker-proxy processes hold the ports. If mac start does not clear them, run sudo systemctl restart docker, which affects other containers, and start again.

Image pull fails with unauthorized or denied​

Run docker login <registry-host> as the user that pulls, including under sudo. Mirror the SDK image too; MAC_REGISTRY does not change SDK_AGENT_IMAGE.

Offline bundle fails validation​

Verify the checksums, replace a damaged archive, and use the complete release bundle. Validate it before you stop a running stack.

Some containers stay in restarting state​

Check mac logs api-server, ports (sudo ss -tlnp) and disk space (df -h). Resolve the cause, then run mac restart <mode>.

Upgrade leaves services stopped​

Upgrade restarts ignore per-user settings. Read /var/lib/mango-ai-center/upgrade-restart.log, move required values to /etc/mango/mac/env, keep the agents' existing token, remove stale MAC_VERSION pins, and load or pull the images. See Upgrading. Then run:

sudo env MAC_IGNORE_USER_ENV=1 mac start <mode>