ESP-Claw Security Best Practices: Protecting Your AI Agent

An ESP-Claw AI agent has access to your home network, potentially your smart home devices, and communicates through your messaging accounts. Security isn’t optional — it’s fundamental. This guide covers the essential practices for keeping your AI agent and your data safe.

Threat Model: What Are We Protecting Against?

Before diving into solutions, let’s understand the risks. An ESP-Claw device faces several categories of threats:

Network-based attacks: Someone on your local network (or who compromises your Wi-Fi) could intercept API keys, read sensor data, or send commands to your smart home devices through the agent.

Physical access attacks: Someone with physical access to the device could extract Wi-Fi credentials, API keys, and conversation history from the flash memory.

API key compromise: If your AI provider API key is leaked, an attacker could run up charges on your account or access your conversation history on the provider’s servers.

Supply chain attacks: Compromised firmware updates could contain malicious code that exfiltrates data or manipulates device behavior.

Privacy risks: Even without an active attack, poor security practices can inadvertently expose personal information through logs, unencrypted communications, or overly permissive API access.

Essential Security Measures

1. Protect Your API Keys

Your AI provider API key (Claude, OpenAI, etc.) is the most valuable secret on the device. If compromised, an attacker can make API calls on your account.

Best practices:

Never hardcode API keys in source code. Use the NVS (Non-Volatile Storage) encrypted partition.
Set spending limits on your AI provider account. Claude and OpenAI both allow monthly budget caps.
Use API keys with minimal permissions. If your provider supports it, create a key that can only access the chat API, not billing or account management.
Rotate keys periodically. Change your API key every 3-6 months, or immediately if you suspect compromise.
Monitor usage. Check your AI provider’s dashboard weekly for unexpected usage spikes.

2. Secure Your Wi-Fi Connection

The ESP32 connects to your home Wi-Fi, which means your network security is the first line of defense.

Best practices:

Use WPA3 if your router supports it. WPA2 is acceptable. Never use WEP or open networks.
Create a separate IoT VLAN or guest network for your ESP-Claw devices. This isolates them from your computers and phones, limiting the blast radius if a device is compromised.
Use a strong, unique Wi-Fi password. The ESP32 stores the password in flash, so a weak password can be extracted by anyone with physical access.
Disable WPS (Wi-Fi Protected Setup) on your router. WPS has known vulnerabilities.

3. Encrypt Communications

All communications between ESP-Claw and external services should be encrypted.

HTTPS for AI API calls: ESP-Claw uses HTTPS by default for all AI provider API calls. The TLS certificate chain is verified against a built-in root CA bundle. Never disable certificate verification, even for testing.

MQTT with TLS: If you’re using MQTT for smart home integration, enable TLS encryption on your MQTT broker.

For Mosquitto, add to your configuration:

listener 8883
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
cafile /etc/mosquitto/certs/ca.crt
require_certificate false

Then configure ESP-Claw to use port 8883 with TLS enabled.

Telegram Bot API: Telegram’s Bot API uses HTTPS by default. No additional configuration needed. However, be aware that Telegram can read your bot’s messages on their servers.

4. Firmware Security

Enable Secure Boot (production deployments): Secure Boot ensures that only firmware signed with your private key can run on the device. This prevents an attacker from flashing malicious firmware.

Enable in menuconfig: Component Config → ESP32-S3 Specific → Enable hardware Secure Boot

Enable Flash Encryption: Flash encryption protects the contents of the SPI flash, including Wi-Fi credentials, API keys, and SOUL.md files, from being read by someone with physical access.

Enable in menuconfig: Security Features → Enable flash encryption on boot

Note: Once enabled, flash encryption is permanent and cannot be disabled without erasing the device. Test thoroughly before enabling on your only device.

Verify OTA updates: ESP-Claw verifies the SHA256 checksum of firmware updates before installing them. For additional security, enable signed OTA updates so the device only accepts updates signed with your private key.

5. SOUL.md Security Considerations

Your SOUL.md personality file can include sensitive information about your home, routines, and preferences. Treat it as confidential.

What to include carefully:

Device names and MQTT topics are necessary but reveal your smart home layout
Personal information (names, schedules) helps the AI but increases privacy risk if the device is compromised
API endpoints and internal network addresses should be minimal

What to never include:

Passwords or API keys (use the encrypted NVS partition instead)
Precise home addresses
Financial information
Medical information

6. Network Segmentation

For the security-conscious, isolating your IoT devices on a separate network segment significantly reduces risk.

Simple approach — Guest network: Most routers support a guest network. Place your ESP-Claw devices on the guest network. They can still reach the internet (for AI API calls) but can’t access devices on your main network.

Advanced approach — VLAN with firewall rules:

Create a dedicated IoT VLAN (e.g., 192.168.10.0/24)
Allow IoT VLAN to reach the internet (for API calls)
Allow IoT VLAN to reach your MQTT broker (for smart home control)
Block IoT VLAN from reaching your computers, NAS, etc.
Allow your main network to reach the IoT VLAN (so you can access the ESP-Claw web interface)

7. Physical Security

If someone has physical access to your ESP32, they can potentially extract all stored data using tools like esptool.py read_flash.

Mitigations:

Enable flash encryption (see above) — the most effective protection
Place devices in enclosures that aren’t easily opened
If deploying in shared spaces, use tamper-evident seals
Consider using the ESP32’s eFuse to permanently disable JTAG debugging

8. Logging and Monitoring

Set up basic monitoring to detect anomalies:

Log all tool calls and their results to MEMORY.md (ESP-Claw does this by default)
Monitor your AI API usage dashboard for unexpected spikes
If using MQTT, log connections to your broker and watch for unknown client IDs
Set up alerts for failed authentication attempts on your MQTT broker

Privacy Considerations

What Data Leaves Your Device?

Understanding data flow helps you make informed privacy decisions:

Data	Destination	Encrypted	Controllable
Chat messages	AI provider (Claude/OpenAI)	Yes (HTTPS)	Choose provider
Telegram messages	Telegram servers	Yes (HTTPS)	Use MQTT instead
MQTT commands	Your MQTT broker	Optional (TLS)	Self-hosted
Sensor readings	Stays on device	N/A	Always local
SOUL.md / MEMORY.md	Stays on device	Flash encryption	Always local
OTA check	GitHub/your server	Yes (HTTPS)	Opt-out available

The AI provider sees your conversation content. This is inherent to using a cloud AI service. If this is unacceptable, use the ESP32-S3 with local inference for basic tasks, or route through a self-hosted AI server.

Data Retention

On-device: SOUL.md, USER.md, and MEMORY.md persist across reboots. Sensor readings are not stored unless you explicitly configure logging.
AI provider: Check your provider’s data retention policy. Anthropic (Claude) does not use API interactions for training by default. OpenAI offers a data retention opt-out.
Telegram: Messages are stored on Telegram’s servers indefinitely unless you use Secret Chats (which bots cannot use).
MQTT: Messages are transient by default (not stored after delivery). If your broker has persistence enabled, messages may be stored on disk.

Security Checklist

Use this checklist when deploying an ESP-Claw device:

No system is 100% secure, but following these practices significantly reduces your attack surface. The goal is to make attacking your device more effort than it’s worth — and to limit the damage if a compromise does occur.