Autonomous Mesh Intelligence for the Off-Grid World.
The AI Responder is a powerful, plugin-based agentic AI designed specifically for Meshtastic mesh networks. It transforms a standard radio node into an intelligent participant capable of real-time network analysis, situational awareness, and automated responder capabilities. Whether running a light-weight local LLM on a Raspberry Pi or leveraging massive frontier models like Gemini, the AI Responder bridges the gap between off-grid LoRa communication and modern artificial intelligence.
The system automatically scales its intelligence based on the selected provider.
- Function Calling (Tools): Frontier models (Gemini, Claude, GPT) proactively query the mesh for telemetry, identify neighbors, and manage their own status using real-time API tools.
- Fallback Metadata Injection: For tool-blind or local models (Ollama), the controller automatically injects structured
[RADIO CONTEXT]blocks, ensuring the AI remains mesh-aware even without native function calling support.
One agent, many brains. Choose the provider that fits your deployment:
- Local (Ollama): Full privacy and off-grid autonomy using models like Llama 3.2.
- Cloud (Gemini, OpenAI, Anthropic): High-reasoning capabilities with advanced tool orchestration and grounding.
Designed for 24/7 autonomous operation in remote environments:
- Radio Watchdog: Automatically detects and recovers from "zombie" connections where the radio hardware is active but the logic link has failed.
- Proactive Reconnection: Universal 10-second retry loop ensuring the bot recovers from service restarts or power cycles without manual intervention.
- Adaptive Rate Limiting: Intelligent message chunking (30s intervals) and ACK verification to prevent mesh congestion while ensuring delivery.
The AI doesn't just respond; it understands its environment:
- Real-time Telemetry: Access to battery, SNR, RSSI, temperature, and humidity for the local node and neighbors.
- Precise Location Tracking: The AI can map out neighbors, complete with exact coordinates, altitude, and calculated distance from the bot.
- Grounding (Gemini): Optional Google Search and Maps integration to provide real-world context for location-based queries.
The AI can now spontaneously send messages to users or manage its own future behavior without being asked:
- Chainable & Stateful Tasks: Ask the AI to "ping me every 15 seconds with the SNR and an incrementing count." The AI uses its Conversation History to maintain state (like counts) across turns and can recursively schedule its own future updates.
- Scheduled Reminders: Ask the AI to remind you about something in 5 minutes or schedule complex recurring pings.
- Condition Watchers: Register alerting rules like "message me when node L4B1's battery drops below 10%" and the AI monitors passively from live mesh telemetry.
- Deferred Telemetry Callbacks: When the AI requests telemetry from a slow node and times out, it registers a background listener. When the data finally arrives from the mesh (seconds to minutes later), it proactively delivers it without requiring the user to ask again.
- Race-Condition Optimized: The AI uses intelligent synchronous polling (0.5s intervals) to ensure that if a mesh node responds quickly, you get a single clean reply instead of redundant proactive alerts.
- Context Isolation: Every user and channel has a secure sandbox, preventing data leakage between conversations.
- Mesh Efficiency: System prompts are tuned for LoRa—delivering high-density, concise information (typically <200 chars).
- Session Management: Direct Message (DM) support for continuous, stateful conversations with proactive timeout alerts.
- Privacy First: With Ollama support, your mesh data never has to leave your local network.
- Low Barrier to Entry: Runs on everything from a Windows desktop to a Raspberry Pi Zero 2W.
- Zero-Config Mesh Discovery: The AI automatically discovers neighboring nodes and can explain the network topology to users.
- Extensible: Architecture allows for easy addition of new Meshtastic tools and AI providers.
| Feature | Status | Description |
|---|---|---|
| Multi-Turn Tools | ✅ Done | Native tool calling for all major AI providers. |
| Adaptive Logic | ✅ Done | Automatic fallback between tools and metadata injection. |
| Radio Resilience | ✅ Done | Implicit ACK detection and Pending ACK Buffer. |
| Proactive Agents | ✅ Done | Scheduled msgs, condition watchers, and deferred telemetry callbacks. |
| Web UI Dashboard | 🚧 In Progress | Portable browser interface for setup and management. |
| Remote Management | 📅 Q3 2026 | Encrypted remote configuration over mesh or secondary link. |
| Health Analytics | 📅 Q4 2026 | Visual metrics of mesh health and AI interaction statistics. |
Architecture: See ARCHITECTURE.md
Note
For detailed configuration options, see CONFIG.md.
Add to your docker-compose.yml:
ai-responder:
image: ghcr.io/ln4cy/ai-responder:latest
environment:
- MESHTASTIC_HOST=meshmonitor
- MESHTASTIC_PORT=4404
- AI_PROVIDER=gemini
- GEMINI_API_KEY=your_key_here
- GEMINI_SEARCH_GROUNDING=true # Optional
- GEMINI_MAPS_GROUNDING=true # Optional
- ADMIN_NODE_ID=!your_admin_id
volumes:
- ai-data:/app/data
depends_on:
- meshmonitor
- ollamaIf using the ollama provider, you must run the Ollama container and pull a model before the bot can respond.
- Start the stack:
docker-compose up -d - Pull the model:
Note: The default model is
docker exec -it ollama ollama pull llama3.2:1bllama3.2:1b. If you changeOLLAMA_MODELin env, pull that one instead.
The ai-responder acts as a "client" to MeshMonitor.
- MeshMonitor must have
ENABLE_VIRTUAL_NODE=trueconfigured. - The
ai-responderconnects to MeshMonitor's virtual node TCP port (default4404). - This allows the AI bot to "see" chat messages on the mesh without needing its own dedicated LoRa radio hardware, leveraging the radio connected to MeshMonitor.
61 62
You can run the responder as a standalone container without Docker Compose:
docker run -d \
--name ai-responder \
--restart unless-stopped \
-e MESHTASTIC_HOST=192.168.1.100 \
-e MESHTASTIC_PORT=4403 \
-e AI_PROVIDER=gemini \
-e GEMINI_API_KEY=your_api_key_here \
ghcr.io/ln4cy/ai-responder:latestTo use with MeshMonitor, ensure MeshMonitor has ENABLE_VIRTUAL_NODE=true.
- Add
ai-responderto yourdocker-compose.yml(see installation above). - Set
MESHTASTIC_HOST=meshmonitor(container name). - Set
MESHTASTIC_PORT=4404(MeshMonitor virtual node port).
This allows the AI to "piggyback" on the radio connected to MeshMonitor.
The AI Responder is fully portable and runs on Windows, macOS, or Linux.
Tip
Upcoming: We are building a Universal Web Management Dashboard to replace all manual setup steps. For now, use the CLI as described in CONFIG.md.
See CONFIG.md for a complete reference of all environment variables and configuration files.
| Environment Variable | Default | Description |
|---|---|---|
INTERFACE_TYPE |
tcp |
tcp or serial |
SERIAL_PORT |
/dev/ttyACM0 |
Serial port (e.g. COM3) |
MESHTASTIC_HOST |
meshmonitor |
Hostname of TCP interface |
MESHTASTIC_PORT |
4404 |
Port of TCP interface |
CONNECTION_RETRY_INTERVAL |
10 |
Seconds between reconnect attempts |
CHUNK_DELAY |
15 |
Seconds to wait before sending the next chunk of a split message |
AI_PROVIDER |
ollama |
Initial provider (ollama, gemini, openai, anthropic) |
OLLAMA_HOST |
ollama |
Hostname for Ollama service |
GEMINI_API_KEY |
- | API Key for Google Gemini |
ADMIN_NODE_ID |
- | Node ID authorized for admin commands. Supports comma-separated list (e.g. !1234abcd,!9e044360) |
ALLOWED_CHANNELS |
0,3 |
CSV list of channel indices to listen on |
HISTORY_MAX_MESSAGES |
1000 |
Max messages to store per user history (Storage) |
HISTORY_MAX_BYTES |
2097152 |
Max size in bytes for history file (Storage) |
OLLAMA_MAX_MESSAGES |
10 |
Max messages sent to Ollama (Context) |
The AI Responder comes with built-in system prompts that handle context isolation and metadata injection. If you wish to customize these prompts, you can mount your own text files into the container.
Create your custom prompt file (e.g., my_prompt.txt):
You are a helpful assistant.
Context: {context_id}
Mount it in Docker Compose:
volumes:
- ai-data:/app/data
- ./my_prompt.txt:/app/system_prompt_local.txt # For Ollama
# - ./my_online_prompt.txt:/app/system_prompt_online.txt # For Gemini/OpenAI/AnthropicThe responder supports several direct commands using the !ai prefix. Note that Direct Messages (DMs) offer full session support, while Channels are for one-off queries.
| Command | Description | Example | Mode Nuance |
|---|---|---|---|
!ai [msg] |
Ask AI: Query the mesh or general knowledge. | !ai what nodes are near? |
Channel: Prefix required. DM: No prefix needed in session. |
!ai -h |
Help: Shows concise consolidated help. | !ai -h |
Context-aware (hides Admin tools in public). |
!ai -m |
Memory: Shows AI context, storage, and slots usage. | !ai -m |
System-wide status for the calling user. |
!ai -n [topic] |
New Topic: Resets context and starts fresh. | !ai -n Mesh Routing |
Channel: Clears history. DM: Starts a named session. |
!ai -end |
End Session: Closes current active session. | !ai -end |
DM Only. Sessions timeout after 5 mins. |
!ai -c ls |
List History: Show your saved conversations. | !ai -c ls |
DM Only. Lists up to 10 saved slots. |
!ai -c [id] |
Load History: Resume a specific conversation. | !ai -c 1 or !ai -c MyTask |
DM: Resumes session. Channel: N/A. |
!ai -c rm [id] |
Delete History: Remove a saved conversation. | !ai -c rm 1 or !ai -c rm all |
Deletes from long-term disk storage. |
Admin commands require your node ID to be in the admin_nodes list (see CONFIG.md).
| Command | Description | Example |
|---|---|---|
!ai -s [rm <id>] |
Scheduler: Manage proactive tasks system-wide. | !ai -s (list), !ai -s add (help) |
!ai -p [name] |
Provider: Switch AI model (Ollama, Gemini, etc). | !ai -p gemini or !ai -p local |
!ai -ch [ls/add/rm] |
Channels: Enable/disable AI on specific channels. | !ai -ch add 2 or !ai -ch ls |
!ai -a [ls/add/rm] |
Admins: Manage the list of authorized admins. | !ai -a add !1234abcd |
Tip
Consolidated Help: Use !ai -h in a DM to see a concise summary of all commands available to you.
Frontier AI providers (Gemini, Claude, GPT) can spontaneously send messages to users based on time or mesh events. No special command needed — just describe what you want to the AI in plain language.
Important
DM-Only Registration: To prevent mesh spam, proactive alerts (timers/watchers) can only be registered via Direct Message. The AI will politely decline if asked in a public channel.
Every proactive task/watcher is assigned a unique ID (e.g., [sched-1], [cond-2], [node-3]). These IDs are shown when the task is registered and are used for management (listing/cancelling).
By default, the AI notifies the requester. However, you can ask it to notify other nodes or even public channels (if the AI is authorized on that channel).
- Example:
!ai Notify me and !9e044360 when L4B1 comes online - Example:
!ai Ping me and channel 0 every 10 minutes
Ask the AI to remind you about something after a delay or at a specific time:
- One-shot (relative):
!ai Remind me to check the batteries in 5 minutes - One-shot (absolute):
!ai Remind me at 10:00 PM to check the mesh - Recurring:
!ai Ping me every 30 seconds for the next 5 minutes - Multi-target:
!ai Remind me and NodeName at 09:00 to swap radios(or use!hexid) - One-off Message:
!ai Tell Node X I'm on my wayor!ai Inform the group on channel 0 that the weather is clear
Monitor a node's telemetry and alert when a threshold is hit:
- Example:
!ai Message me when node L4B1's battery is below 10% - Example:
!ai Alert me if the SNR on !9e044360 drops below -12 - Supported metrics:
battery_level,voltage,temperature,humidity,barometric_pressure,iaq,snr - Supported operators:
<,>,<=,>=,==
Leverage the AI's ability to maintain state and schedule future actions:
- Stateful Counting:
!ai For the next minute, ping me every 15 seconds with my SNR and an incrementing count starting at 1 - Recursive Monitoring:
!ai Every 10 minutes, check the temperature of L4B1. If it's above 35C, alert channel 0, otherwise just remind yourself to check again in 10 minutes. - Data Refresh Loops:
!ai Watch node XYZ. Every time its battery changes, send me the new value and the current SNR.
Get a notification as soon as a specific node is heard on the mesh:
- Example:
!ai Notify me when L4B1 comes online - Example:
!ai Message me and !9e044360 when node XYZ is seen
You can query and cancel your own tasks at any time:
- List your tasks:
!ai What alerts do I have?or!ai show my reminders - Cancel a task:
!ai Cancel [sched-1] - Cancel all:
!ai Cancel all my alerts
When the AI requests telemetry from a slow mesh node and times out, it registers a background callback automatically. When the data eventually arrives, the AI proactively sends you the result without requiring you to ask again.
- Use sessions in DMs for back-and-forth conversations to save typing
- Name your sessions descriptively for easy recall later
- Delete old conversations when you hit the 10-slot limit
- Use
!ai -nin channels when you want to start a fresh topic - Check
!ai -mperiodically to monitor storage usage - Sessions timeout after 5 minutes - you'll see the session indicator disappear from responses
This project is licensed under the MIT License.
- Meshtastic Integration: This project depends on the
meshtasticPython library which is licensed under GPLv3. - Inspiration & Components: MeshMonitor components included in this project are licensed under the BSD 3-Clause License.
Important
GPL Compatibility Note:
Because this responder imports and links with meshtastic (GPLv3), any distributed binary or Docker image containing these components is effectively subject to the terms of the GPLv3.
If you are building upon this project and plan to distribute it, ensure you comply with the requirements of the GPLv3 for the combined work.
See the LICENSE file for the full text.