MITM configs
The config file each MITM needs, written onto every box in a group.
Installing a MITM is half the job. Aegis, Atlas and GoCheats all read a JSON file next to themselves and do nothing useful until it has the correct parameters.
Youu can fill that file on the device group, in Settings → Device groups → MITM data.
What a group declares
| Field | What it is |
|---|---|
| MITM package | The scanner these boxes run. Also what the MITM column shows. |
| Column header | Shorter name for that column. Defaults to the last dotted segment. |
| Config file path | Where the file goes on the box, eg. /data/local/tmp/aegis_config.json. |
| Config JSON | The file's contents, with placeholders. |
| Install on join | Builds every box joining this group is given, before anybody asks. Empty by default. |
The Fill from buttons put in the real shapes for Aegis, Atlas, GoCheats,
Cosmog, and Lunala, paths and key sets. Aegis (Redroid) and Cosmog (Redroid)
are the container equivalents, with "workers": "{{device.workers}}"
instead of a fixed number, so each container gets the count its machine was
scaled with.
Groups support both Agent modes (traditional methods) and Direct Mode / RPC mode (direct protocol workers such as Lunala and standalone RPC daemons).
Direct Mode (RPC mode) & Dual Format Support
In addition to traditional scanners that inject into the Android game process, Magnemite natively supports Direct Mode (also known as RPC mode).
What is Direct Mode?
- Protocol-level workers: Engines in Direct Mode establish direct WebSocket connections to Rotom without running or requiring the Pokémon GO game application.
- Low footprint & high density: Because there is no 3D graphics rendering or heavy Android app lifecycle, machines can host many more concurrent workers.
- Dedicated fleet monitoring: Magnemite automatically recognizes Direct Mode devices (by package name or RPC group label), displaying a dedicated
RPCbadge in the fleet table and exposing the Direct Status Card on device details instead of reporting the game app as stopped.
JSON & TOML Configuration
Magnemite groups support both JSON and TOML configuration templates:
- JSON (
.json): Used by standard scanners and JSON-based RPC daemons. - TOML (
.toml): Natively parsed and rendered for TOML-configured engines such as Lunala (/app/config.toml).
The format is the config file path's to say: a path ending in .toml is TOML, anything else is JSON.
The placeholders are the same in both, with one difference. JSON has every
placeholder inside a string. TOML is typed, so a number may stand outside
quotes — workers = {{device.workers}} — and anything else outside them is
refused at Save. Inside "…" a value is escaped, so a box named
Kitchen "spare" cannot end its own string and add a key.
Cosmog
Cosmog 2 is the odd one, and the Cosmog preset is
aconf's cosmog_config.toml key for key:
[rotom]
rotom_worker_endpoint = "ws://YOUR_ROTOM_URL:7070/"
rotom_device_endpoint = "ws://YOUR_ROTOM_URL:7070/control"
rotom_secret = "YOUR_ROTOM_SECRET"
use_compression = true
[general]
device_name = "{{device.name}}"
workers = 50
klefki_token = "YOUR_KLEFKI_TOKEN"What is different from Aegis and GoCheats:
-
TOML in its own directory,
/data/local/tmp/cos/config.toml, beside the binary. The directory is created if it is not there. -
It is not an app. Cosmog is a binary named
com.nianticlabs.pokemongorun out of/data/local/tmp/cos, with no package installed, soam force-stopand a launcher do nothing to it. The preset therefore fills the group's hooks too — aconf's own stop and start:pkill -9 -f 'com\.nianticlabs\.pokemong[o]' || true cd /data/local/tmp/cos && setsid nohup ./com.nianticlabs.pokemongo >/dev/null 2>&1 &They are what an install and Rewrite config stop and start it with. The
[o]keepspkillfrom matching the shell that runs it.
Installing it
Cosmog is filed under the package com.sy1vi3.cosmog. No such package is
ever installed; the name is what a version, a rollout and the MITM column are
keyed on, and the agent answers for it from cos.version instead of asking
pm.
The bundle is the zip as it is published — the binary at its root and
lib/libart.so beside it. Upload it, or paste its link, on
Manual deploy. The hub recognises it by those two entries
and refuses a zip missing either: the binary does not start without the libart
it was built against, so the pair travels as one artifact with one checksum.
Nothing inside says which release it is, so the version is typed — or read
off a name like cosmog-2.1.3.zip.
Deploying it unpacks the zip into /data/local/tmp/cos, each file written
beside its destination and renamed over it, so a Cosmog that is still running
is replaced rather than half-overwritten. Whatever else the zip holds comes
along; a config.toml in it never does. Then the group's config is written and
the post-install hook starts it.
The game is the other half. Cosmog does not run Pokémon GO; it loads the
game's libNianticLabsPlugin.so and reads its APKs off disk. So on a box whose
group's MITM is Cosmog, deploying an ordinary Pokémon GO build installs
nothing. The same .apkm every other group installs is unpacked instead:
| From the bundle | To |
|---|---|
base.apk | cos/files/base.apk |
split_config.arm64_v8a.apk | cos/files/split_config.arm64_v8a.apk |
lib/arm64-v8a/libNianticLabsPlugin.so in that split | cos/lib/libNianticLabsPlugin.so |
That is aconf's pogo_lib, without unzipping a split by hand. The box then
reports that build as its Pokémon GO version, so the Fleet table shows which
game Cosmog is loading and a rollout skips a box already on it.
Put both in the group's Install on join — the game, then Cosmog — and a new box builds itself: the game's files first, then the binary, its config, and the start.
Three things to know:
- It needs an agent that knows how. One that predates this would
pm installthe game onto a Cosmog box, so a job for an older agent waits, saying so, until the agent has updated. - An installed Pokémon GO is left alone. aconf uninstalls the app from a Cosmog box; Magnemite does not delete an app's data on its own. The stop hook above does kill it, since it matches by the same name, so remove it yourself if the box still has one.
- Zygisk and the denylist are not touched. aconf switches both on in Magisk on first install. That is box setup, not Cosmog's files, and stays yours.
A Lunala group template is the same idea in a container:
[rotom]
rotom_worker_endpoint = "ws://YOUR_ROTOM_URL:7072"
rotom_device_endpoint = "ws://YOUR_ROTOM_URL:7072/control"
rotom_secret = "YOUR_ROTOM_SECRET"
[general]
device_name = "{{device.name}}"
workers = 1
auth_token = "YOUR_KLEFKI_AUTH_TOKEN"Install on join
A box that has just enrolled is in its group with nothing on it — a container that has only now come up, or hardware somebody has just flashed. Everything else the fleet does assumes the scanner and its MITM are already there, so the first move after every scale-up was a trip to Manual deploy to install the same two builds on the same kind of box again.
Put those builds in the group's Install on join and the box does it itself. A container coming up at four in the morning after a scale-up arrives with the scanner on it.
This is the one control here that installs with nobody watching
It is empty on every group and nothing happens until somebody fills it — the same care the monitoring rules are seeded disabled with. An upgrade that starts installing on its own is the version of this nobody asked for.
What it does, precisely:
- One build per package. Two builds of one package would mean a new box installing one over the other in whichever order the scheduler happened to pick, so the second is refused with the first one named.
- A build, not "the newest". Installing whatever is latest is what a rollout is for, and answering it here would make every new box the first to try a version nobody chose. This answers the narrower question — what does a box need before it is any use — and that is a build somebody picked and has already seen work.
- Cached builds only, because that is what a rollout accepts. One listed by a source and not yet downloaded is refused when you add it, rather than at the one moment nobody is watching.
- Each build is its own rollout, so they appear on Rollouts noted
joined its groupand are followed, retried and cancelled like any other. - One after the other, the MITM last. The builds go in the order they were
added, except the group's MITM package, which always goes last, and each
waits for the one before it to succeed: until then its rollout shows as
pending, after whatever it waits for. The MITM's install is the one that writes its config and starts it, so it wants the game already on the box. - No hooks, but the one that starts the MITM. The game goes in with neither hook: on a new box there is nothing running to stop, and the MITM a post-install hook would start is not installed yet. The MITM's own install runs only the post-install hook, after its config is written.
- A failed game holds the MITM back. It stays
pendingrather than going in without it. Retry on the failed job lets it go once that succeeds, and Start now on the waiting rollout sends it regardless. - Not before the box has settled. Nothing starts until the box has been up
for Settings → Tuning → New boxes settle for (120 s), counted from its
boot. A minute-old Android is still compiling its packages and settling
Magisk, which is a poor moment to push a 170 MB game into. The job says
held 118s while the box settles after booting;0installs on enrolment. - A box that already has one gets nothing for it. The check is what the box
reports installed, not whether it has enrolled before — so a re-enrolment
queues nothing, and a box whose
/datawas wiped gets everything again, which is exactly when it needs to. - Removing a build from the list uninstalls nothing. The boxes that got it keep it; the list only says what the next box gets.
A box that enrolled on a token without auto-approve is skipped, because a rollout cannot target an unapproved box. It gets its builds the moment you approve it.
Putting boxes in a group
One box: the Group select on its device page. Many: pick them on Fleet and press Change group in the bar at the bottom, the same place Rename lives. The dialog says where the selection is now and how many actually move, boxes already in the target group are left alone.
Moving a box changes what it installs, not what is on it: the new group's config, its install hooks and its concurrency cap apply from the next deploy. Nothing is pushed at the moment of the move.
Placeholders
Anything a box has to say about itself is a placeholder, substituted per device before the file is written.
{
"authBearer": "s3cret",
"deviceName": "{{device.name}}",
"rotomUrl": "http://rotom.lan:7072",
"workers": 8
}Available: device.id, device.name, device.serial, device.model,
device.manufacturer, device.androidVersion, device.abi, device.localIp,
device.publicIp, device.rotomOrigin, device.rotomDeviceId,
device.workers, group.name.
device.workers is how many workers a Redroid container is configured for: its
own number, else its machine's, else Settings → Tuning, as set on the
Machines page. It is what makes
a machine's capacity a number the dashboard owns — containers times workers —
rather than one hard-coded into the group's config, where it would be the same
for every machine in the group.
A group that mixes containers and real hardware
Only a container has a worker count, so {{device.workers}} is empty on a TV box — and an empty
known placeholder is refused when the config is rendered, naming the box. That is the refusal
working, and the fix is a group per kind rather than a default nobody chose.
Two things are refused rather than papered over:
- An unknown placeholder.
{{device.nmae}}would otherwise be written through literally, and a scanner started against that is worse off than one never configured. Caught at Save. - A known placeholder with no value on a box. Substituting
""is how a whole site ends up reporting to Rotom under the same blank origin. Caught when the config is rendered for a deploy, naming the box and the field, and logged as a warning on that box's job.
rotomOrigin is empty until Rotom matches the box
So a first deploy on a fresh fleet often refuses it on most boxes. That is the
refusal working. Either use {{device.name}}, which every box has, or deploy
again once the Rotom sync has run.
When it is written
With the install. A rollout of a group's own MITM carries that group's config (if toggled on). The agent writes it after the install verifies and before the post-install hook. A join install is such a rollout, so the MITM in a group's Install on join arrives already configured.
By hand, on one box. The device page's Execute has two buttons built from the box's group:
- Show MITM config —
catof the group's config path, so you see the file as it is on the box right now. - Rewrite MITM config… — the group's config rendered for this box, in an
editor. Write and restart writes it with nothing installed: the box
stops the MITM with the group's pre-install hook, writes the file exactly as
an install does, and starts it again with the post-install hook. A group
without hooks gets
am force-stopand the app's launcher. An edit goes to this box alone; the group keeps its own template.
The restart is the point of the second one, because a running MITM does not
re-read a file it has already read. It needs an agent that knows push_config
(1.0.5 or later); an older one says so instead of offering the button.
When a container's workers change. A Redroid box whose
worker count moves — its own, its
machine's, or the one in Settings — has its config rewritten by the hub, the way
Rewrite config does it, a few boxes at a time. Only a config that says
{{device.workers}} is rewritten; any other is the same file either way.
Saving a group writes to the database and nothing else. An edited config reaches the fleet on the next deploy of that group's MITM (if toggled on), or a box at a time with Rewrite config, and not before.
How it lands
The agent takes the config object off the install job, or off push_config
for a rewrite by hand, and:
- Writes to a temp file and renames it into place, so a scanner reading the file while it is replaced sees the old bytes or the new ones, never a half-written middle.
- Reads the file back and reports its sha256. That answers "what is on the box", where hashing what the hub sent would only answer "what did the hub mean".
A config that cannot be written fails the job, rather than leaving a scanner running on someone else's settings. The downloaded bundle is kept, so the retry costs an attempt and not a second download.
The config holds credentials
authBearer, deviceAuthToken, an email address. It is never written to the hub's log, never
into an audit entry.
Lineage
The paths and the per-box name substitution are both aconf's, which has been doing this on the same hardware for years. Credits to @TechG3n for the original idea.