Device contacts, the cache layer, the ignored and blocked flags, and the settings that tie everything together — plus how to migrate from the official MeshCore apps.
This guide explains how contact management works in mc-webui and how it differs from the official MeshCore apps for Android and iOS. If you've used the official apps before, some of the concepts introduced here — especially cache contacts, the ignored flag, and blocked contacts — may be new to you. This document walks through all of them, explains why they exist, and provides recommended settings so you can run a tidy contact list without constantly fighting the 350-contact device limit.
The official MeshCore applications for Android and iOS keep everything simple: every contact you receive an advertisement from is added to your device, and the only way to get rid of one is to delete it outright. That works fine for light mesh activity, but once you sit in a busy area — or leave your node running for weeks — you quickly hit the hard limit of 350 contacts on a MeshCore device. After that, new contacts either fail to add, or older ones start getting dropped.
mc-webui takes a different approach. It introduces a cache layer in its own database that mirrors and extends what lives on the device. This gives you two tiers of storage:
@mentions.On top of those two tiers, mc-webui adds two flags — ignored and blocked — that let you silence contacts without deleting them. Combined with the new Contacts settings tab, the goal is to let you keep a large, healthy overview of the mesh around you while only occupying device slots for the contacts you actually talk to.
Every MeshCore device keeps its own contact list in firmware storage. You can see it in Contact Management → Existing Contacts and edit it through the web UI. Each device contact is one of four types:
| Type | Meaning | Typical use |
|---|---|---|
| COM (companion) | Another user's node | Direct messages |
| REP (repeater) | A repeater node | Repeater admin commands, path building |
| ROOM (room server) | A room server | Login + chat in group rooms |
| SENS (sensor) | A sensor node | Telemetry queries |
The MeshCore firmware stores contacts in limited flash memory. Most builds allow up to 350 contacts; some configurations can go higher (reportedly up to 450), but this is hardware and firmware dependent. Once the device is full, any new advertisement that would create a fresh contact has nowhere to go, and you start losing visibility of the mesh.
mc-webui highlights this pressure with a colored counter above the Existing Contacts list:
Only contacts stored on the device can be used for:
Everything else — appearing on the map, being available in @mentions, being usable as a path node — does not require the contact to be on the device. That's where the cache comes in.
A cache contact is stored only in the mc-webui SQLite database. It never occupies a slot in the device firmware. In the Existing Contacts view, cache contacts show a Cache badge next to their name.
A contact becomes a cache contact in one of three ways:
Cache contacts keep most of what makes a contact useful:
@mentions — you can tag cache contacts in channel messages.In short: treat the cache as an address book for people and nodes you want to remember but don't actively talk to. Promote them to the device only when you need to interact directly.
Even with Manual approval enabled, you may want to silence specific nodes entirely — spammers, misconfigured repeaters flooding adverts, or test nodes you simply don't care about. That's what the ignored flag is for.
An ignored contact is a special case of a cache contact: the record still exists in the database, but:
To see ignored contacts, switch the type filter in Existing Contacts to "Ignored". Each ignored row offers a Restore action that clears the flag and moves the contact back to the normal list (still cache-only until you push it to the device).
You can ignore a contact in two ways:
The ignored flag is one-way silent: your node still sees the adverts under the hood, they just don't reach your inbox. This is different from blocking, described next.
Where ignoring handles adverts, blocking handles everything else. A blocked contact is another special case of a cache contact:
Blocking is the right tool for a contact you consider hostile or abusive on public channels, not just noisy. The distinction matters:
| Behaviour | Ignored | Blocked |
|---|---|---|
| Adverts suppressed | ✔ | ✔ |
| Hidden from Existing Contacts by default | ✔ | ✔ |
| Their group-chat messages appear in your UI | ✔ | ✘ (dropped) |
| Still searchable via type filter | "Ignored" | "Blocked" |
| Reversible with "Restore" | ✔ | ✔ |
To block a contact, click the Block button on their contact card. To restore, switch the Existing Contacts type filter to "Blocked" and click Restore.
A note about DMs: the primary path a stranger takes to reach you is a public-channel message or an advert. If someone is already a DM contact and you want to shut them out, block them and delete the contact from your device — otherwise the device can still accept DMs from them at the firmware level.
Contact management is a two-way street. Every contact in your Existing Contacts list has a button that moves it to the other tier:
@mentions, the map, and path configuration.Both operations are reversible at any time. The database keeps the contact's type, last-seen timestamp, public key, location, and path history intact, so promoting and demoting a contact never loses information.
Typical flow:
All contact-wide behaviour lives under Settings → Contacts (click the gear icon or use the FAB button). Three toggles control how new contacts reach you:
When off (the default MeshCore behaviour), every new advert is added straight to the device. This is what the Android/iOS apps do.
When on, new adverts are written to the mc-webui cache and surface in Pending Contacts for review. Nothing reaches the device until you explicitly approve the contact. This is the foundation for every other contact-hygiene feature, because it's only in this mode that mc-webui has a chance to intercept new adverts before they consume a device slot.
The setting is written to the device itself via the set_manual_add_contacts firmware command, so it persists across container restarts.
A purely UI-level toggle. When on:
Use this when you know you'll receive many adverts (busy mesh, holiday weekend, a neighbour's flood-advert test) and you don't want your phone or desktop lighting up every few seconds.
This toggle only matters when Manual approval is on — without manual approval, new adverts bypass the cache entirely, and there's nothing for the UI to suppress. mc-webui disables the checkbox while Manual approval is off.
When on, every new advert that would normally land in Pending Contacts is instead written to the cache and immediately marked as ignored. The practical effect:
This is the closest thing mc-webui offers to "silent observation": your node absorbs the topology of the mesh around it without adding noise to your inbox or burning through device slots. It's also the option that pairs best with a small, hand-curated set of device contacts.
Like suppression, this toggle is gated on Manual approval = on. Without manual approval, new adverts go to the device, not the cache.
For the vast majority of users running mc-webui long-term, the recommended configuration is:
| Setting | Recommended |
|---|---|
| Manual approval enabled | On |
| Suppress new advert notifications | On (reduces notification pressure) or Off (if you like seeing mesh activity) |
| Automatically add new contacts to "Ignored" | On |
This combination gives you:
If you prefer to see new adverts as they arrive (for example, to celebrate a new node appearing in your area), turn off "Automatically add new contacts" and "Suppress new advert notifications", but keep Manual approval on. You'll then triage each advert manually from Pending Contacts.
You hear a repeater three valleys away. It's useful as a route hop for a DM contact, but you're never going to admin it.
Someone's repeater keeps advertising every few seconds (misconfigured timing). You don't want to look at its adverts, but you also don't want to block legitimate traffic on channels it relays.
A node keeps flooding #general with unwanted messages.
You want to add three friends you met in person. None of them advertise from your location yet.
You're about to travel into a dense mesh and expect many new adverts. Your current count is 310 / 350.
If the counter in Existing Contacts is red and you can no longer add new contacts to the device, work through this sequence:
Contact Management pages use a consistent set of badges and icons so you can tell each contact's status at a glance:
COM (blue), REP (green), ROOM (cyan), SENS (yellow).Cache, present only on contacts that live in the database but not on the device.If you ever need to know whether a contact is on the device or only in the cache, the answer is always one glance at the Cache badge.
Auto-Cleanup (configured at the bottom of the Contact Management page) operates on device contacts only. It never touches cache contacts or the ignored/blocked flags. The reasoning is straightforward:
Combined with Auto-ignore, this keeps your device hovering at a healthy contact count without you thinking about it. Adverts you never interact with flow into the ignored cache; device contacts that go quiet for 30+ days roll off automatically; everything you actively use stays put.
It's worth spelling out the distinction one more time, because the vocabulary doesn't exist in the official apps:
Neither action is broadcast to the mesh. The node you ignore or block has no way of knowing — from their perspective, nothing changes. Their adverts still travel the network; their messages still reach other users. Only your own node stops rendering them.
Both actions are reversible. Nothing is deleted from the database unless you also hit Delete — the flags are just another column in the contact record. If you change your mind, switch the Existing Contacts filter to "Ignored" or "Blocked" and click Restore.
Q: I've been using the Android app and my device is already at 350 contacts. Where do I start?
Follow What to Do When You Hit the 350 Limit. The short version: turn on Manual approval, turn on Auto-ignore, then use Move to Cache (or the Cleanup tool) to demote contacts you don't actively use.
Q: Do cache contacts count against the 350 device limit?
No. The 350-limit applies only to contacts stored on the MeshCore firmware. Cache contacts live in the mc-webui database, which is effectively unlimited.
Q: Will cache contacts sync to my Android/iOS device if I pair it later?
No. The cache is specific to mc-webui. The official MeshCore apps only know about what's on the device. If you connect the same device to the Android app, you'll see only the device contacts, not the cache.
Q: Can I send a DM to a cache contact?
Not directly. Click Push to Device first; the contact then occupies a device slot and becomes DM-ready. You can Move it back to the cache when you're done.
Q: What happens if I delete a cache contact?
The full record is removed from the mc-webui database. Ignored / blocked flags, path history, last-seen timestamps, everything goes. The next advert from that node will re-create it — but without any of the history.
Q: I enabled Auto-ignore and now my Pending Contacts list is empty. Is that normal?
Yes. That's exactly what Auto-ignore is designed to do: new adverts bypass the Pending list and land directly in the cache with the ignored flag set. To review recently ignored nodes, open Existing Contacts and switch the type filter to Ignored.
Q: Why is Manual approval required for Suppress and Auto-ignore?
Both features operate on the cache (pending or newly arrived adverts in the database). Without Manual approval, adverts go straight to the device — there's nothing to suppress or ignore at the cache level. Enabling the toggles in that mode wouldn't change anything, so the UI disables them.
Q: Can I still use @mentions for cache contacts?
Yes. @mentions autocompletes against the full database, including cache-only contacts. This is one of the main reasons the cache exists.
Q: What's the difference between "Last Advert" and "Last Modified" in the Cleanup tool?
Last Advert is the timestamp of the most recent advertisement received from the contact — it's the most honest signal that a node is still alive. Last Modified reflects when anything about the contact record changed (including path updates from your own actions), so it can be misleading. Prefer Last Advert unless you have a specific reason not to.
Q: Can I block a contact by name pattern rather than a specific key?
mc-webui supports a blocked_names table for blocking by name. Currently this isn't exposed in the UI; the individual-contact Block action is the supported path for day-to-day use.
Q: Will the cache grow forever?
Technically yes — every unique advert you've ever received leaves a record. In practice, the database stays small (a record is a few dozen bytes), and you can always run the Cleanup tool against cache entries if you want to prune them manually.