Troubleshooting

DNS on AndroidCopy Anchor Link

lookup magnemite.example.com: no such host

Why it happensCopy Anchor Link

The agent is built with CGO_ENABLED=0 so it is one static binary that needs no NDK to cross-compile and no shared libraries on the box. The cost is that Go stops calling the system resolver and uses its own, written in Go — and that resolver learns which nameservers to use by reading /etc/resolv.conf.

Android does not have that file. Bionic, Android's libc, asks the netd daemon over a socket instead, and publishes the current servers as system properties:

adb shell getprop net.dns1

So everything on the box resolves names except a CGO-free Go program, which finds no config, has no servers to ask, and fails every lookup.

The fixCopy Anchor Link

It lives in agent/internal/netfix. At startup the agent checks for /etc/resolv.conf; if the file is missing it installs a net.Resolver whose dialer walks this list, rotating to the next entry whenever a server refuses a connection — common on a LAN where the router's resolver black-holes.

What version is actually runningCopy Anchor Link

The Status page carries the version of every piece.

Each number comes from the matching line of the repo's VERSION file.

Reading what the box actually printedCopy Anchor Link

The ⋯ menu on a device page has Logcat (.zip) for a snapshot you can keep and Live logs for logcat as it happens. What each contains, and what to look for, is in reading a box's logs.

An agent that will not updateCopy Anchor Link

The hub only sends agent_update to a box whose reported version differs from its target, that is not mid-job, and whose ABI it has a build for. Check the Status page for the target version and AGENT_AUTO_UPDATE, the device page for the version that box reports, and the box's own log for self-update: lines.

Check the full flow in updating the agent.

A MITM installed without its configCopy Anchor Link

The app is on the box and starts, then says its config is missing: Aegis prints The configuration file aegis_config.json is invalid or inexistent. The MITM's job on Rollouts says why the hub sent none, as a warning:

A box already in that state: Execute → Rewrite MITM config on its device page writes the group's config and restarts the MITM, with nothing reinstalled (an agent of 1.0.5 or later). On an older agent, a Manual deploy of the same MITM build with the config switch left on does it by reinstalling in place.

Small /dataCopy Anchor Link

Boxes need roughly 450 MB free: a 172 MB bundle unpacks to ~250 MB and both sit on disk at once. The agent refuses to start an install below that rather than filling the partition. Devices table shows free space per device and warns under 500 MB, when things are already tight.

EgressCopy Anchor Link

A full rollout to 200 boxes is ~35 GB off your server. Settings → Tuning → Max concurrent jobs paces it

A box enrolled but never appears online?Copy Anchor Link

I know the feeling, such a headache. Check the following:

When the table settles nothing, read the agent's own log. It is written to /data/adb/magnemite/agent.log — by the Magisk service on a box, by magnemite-start.sh in a Redroid container — rotated to agent.log.1 at 2 MB, and it is where enrollment and connection failures actually print:

# the whole log, and the rotated previous one
adb shell su -c 'cat /data/adb/magnemite/agent.log'
adb shell su -c 'cat /data/adb/magnemite/agent.log.1'

# follow it live while you retry
adb shell su -c 'tail -f /data/adb/magnemite/agent.log'

# just the enrollment and connection lines
adb shell su -c 'grep -E "enroll|connect|reconnecting|connection lost" /data/adb/magnemite/agent.log'

No log file at all means the module never started. Check it is enabled and that the binary is there:

adb shell su -c 'ls -l /data/adb/modules/magnemite-agent/'
adb shell su -c 'ps -A | grep magnemite'
adb logcat -d | grep -i magnemite

Redroid boxesCopy Anchor Link

Three failures particular to containers:

A new device row on every restart is the serial. A container has no ro.serialno of its own, so the agent falls back to a MAC that Docker reassigns on recreate, and the hub — which keys a device on its serial alone — sees a box it has never met. Give each container an explicit, unique ro.serialno.

No agent process means init never started the service. Redroid normally runs SELinux permissive and magnemite.rc sets no seclabel for that reason; an image that enforces denies the service, and the denial is in logcat:

adb shell 'ps -A | grep magnemite-agent'
adb shell logcat -b all | grep -i magnemite
adb shell 'ls -l /system/etc/init/magnemite.rc /data/adb/magnemite/'

Identical load and temperature across boxes is correct. Linux has no per-container load average and a container has no thermal sensor, so both are the host's. Uptime and storage are the box's own; memory is too, but only when the container has a mem_limit.

Downloads 401 at the edgeCopy Anchor Link

/files/* is gated by forward_auth against the hub's /internal/authz. A 401 means the device token the box presented is not one the hub recognises, most often a box restored from a backup image whose device row was deleted. Delete its config.json device token and let it enroll again.