Arduino Cloud Agent Guide: Install, Connect, and Fix Errors

What is the Arduino Cloud Agent?

The Arduino Cloud Agent (historically known as the Arduino Create Agent) is a lightweight, background middleware application that bridges the gap between your web browser and physical microcontroller hardware. While modern browsers have begun implementing the WebSerial API, native browser support is often insufficient for complex maker workflows. Browsers cannot reliably toggle hardware strapping pins, manage ESP32 ROM bootloaders, or execute Over-The-Air (OTA) firmware deployments without external help.

The Agent solves this by spinning up a local, secure REST server on your machine (typically listening on https://localhost:8991). When you use the Arduino IoT Cloud or Web Editor, the browser sends compilation payloads and serial commands to this local server, which then translates them into raw USB serial or network socket commands for your board. According to the Mozilla Developer Network (MDN) WebSerial API documentation, browser-level serial access requires explicit user interaction per session and lacks advanced bootloader toggling capabilities, making the Arduino Cloud Agent an absolute necessity for seamless IoT development.

System Prerequisites for Modern Workflows

Before initiating the setup, ensure your development environment meets the current 2026 hardware and software baselines. The Agent is remarkably lightweight, requiring less than 50MB of RAM, but OS-level security policies can interfere with its local server operations.

Windows: Windows 10 (22H2 or later) or Windows 11 (23H2/24H2). Microsoft Edge or Google Chrome recommended.
macOS: macOS Sonoma (14.x) or Sequoia (15.x). Safari is not recommended due to strict WebSerial and local certificate sandboxing; use Chrome or Firefox.
Linux: Ubuntu 22.04/24.04 LTS, Debian 12, or Fedora 39+. You must have libusb and proper udev rules configured.
Hardware: Any official Arduino board (Uno R4, Nano ESP32, Portenta) or third-party ESP32/SAMD boards with valid USB-UART bridges (CH340, CP2102) or native USB-CDC.

Step-by-Step Installation Guide

Getting the Agent running requires downloading the correct binary for your architecture. Always source the installer directly from the Arduino Software Download Portal or the prompt within the Arduino IoT Cloud dashboard.

Windows 11 Installation

Download the Arduino_Create_Agent_setup.exe file. During installation, Windows Defender SmartScreen may flag the executable because the installer modifies local firewall rules to allow loopback traffic on port 8991. Click More Info and Run Anyway. Once installed, the Agent will reside in your system tray. Right-click the tray icon to verify the version number and ensure the status reads 'Agent is running'.

macOS (Sonoma and Sequoia) Installation

Download the .pkg installer. macOS Gatekeeper is highly aggressive with background services. After running the package installer, the Agent may be blocked from launching automatically. Navigate to System Settings > Privacy & Security, scroll to the Security section, and click Open Anyway next to the blocked Arduino Create Agent extension. You may need to enter your administrator password to authorize the local network listener.

Linux (Ubuntu and Debian-based) Installation

Linux users should avoid the generic binary tarballs and instead use the provided install_script or the .deb package. The script automatically configures the systemd service and sets up the necessary symlinks. Open your terminal and run:

curl -fsSL https://raw.githubusercontent.com/arduino/arduino-create-agent/main/install.sh | sh

After installation, restart your browser entirely to clear any cached WebSocket rejections.

The Localhost Certificate Hurdle (Critical Edge Case)

The most common reason the Arduino Cloud Agent fails to connect to the IoT dashboard is a Self-Signed Certificate Rejection. Because the Agent runs a local HTTPS server to satisfy browser security requirements (mixed-content policies block HTTP requests from HTTPS pages), it generates a self-signed SSL certificate for localhost.

Pro-Tip: If the IoT Cloud dashboard displays 'Plugin not found' or 'Agent disconnected' despite the tray icon showing green, your browser has likely rejected the local certificate. Open a new tab and navigate to https://localhost:8991. The browser will show a 'Your connection is not private' warning. Click Advanced and then Proceed to localhost (unsafe). This forces the browser to trust the local certificate, instantly restoring connectivity to the Cloud dashboard.

Linux Deep Dive: Solving the brltty USB Conflict

If you are on Ubuntu 22.04 or newer and your ESP32 or Arduino Nano clone (using the CH340 chip) is recognized but immediately disconnects or throws a 'Port Busy / Access Denied' error in the Cloud Agent, you are likely a victim of the brltty daemon. This is a background service for Braille displays that aggressively claims generic USB-Serial interfaces.

To resolve this hardware hijacking, follow these steps:

Open your terminal and check if the service is running: systemctl status brltty
If active, remove the package entirely (unless you require a Braille display): sudo apt remove brltty
Next, ensure your user account has permission to access serial ports by adding yourself to the dialout group: sudo usermod -a -G dialout $USER
Log out and log back in, or reboot your machine to apply the group policy changes.

For custom boards using the CP2102 chip, you may also need to create a custom udev rule to prevent ModemManager from probing the port. Create a file at /etc/udev/rules.d/99-arduino.rules containing:

ATTRS{idVendor}=='10c4', ATTRS{idProduct}=='ea60', ENV{ID_MM_DEVICE_IGNORE}='1'

Reload the rules with sudo udevadm control --reload-rules && sudo udevadm trigger.

Troubleshooting Matrix: Common Agent Errors

When working with the official Arduino Cloud documentation and real-world hardware, edge cases inevitably arise. Use this matrix to diagnose and fix agent-related failures.

Error Message / Symptom	Root Cause	Actionable Fix
'Agent not found' or 'Plugin missing'	Browser blocked the local REST server or the Agent service crashed.	Restart the Agent from the system tray. Accept the certificate at `https://localhost:8991`. Disable browser extensions that block local WebSockets.
'Port Busy' or 'Access Denied' during flash	Another application is holding the serial port lock (e.g., Arduino IDE Serial Monitor, Cura, or 3D printer slicers).	Close all other IDEs and serial terminals. On Linux, check for `brltty` or `ModemManager` interference as detailed above.
'Compilation successful, but Upload failed' (ESP32)	The ESP32 requires manual bootloader invocation. The Agent cannot toggle the BOOT/RESET pins on generic clone boards.	Hold the 'BOOT' button on the ESP32 board, click 'Upload' in the Cloud dashboard, and release the button when the console says 'Connecting...'.
'OTA Update Failed: Partition Error'	The selected board memory partition scheme does not allocate space for dual OTA app slots.	In the IoT Cloud device setup, ensure the partition scheme is set to 'Default 4MB with spiffs' or a scheme explicitly supporting OTA. Avoid 'Huge APP'.
Agent Tray Icon is Red / 'Error starting HTTP server'	Port 8991 or 8992 is occupied by another local development server or blocked by a third-party antivirus firewall.	Check for port conflicts using `netstat -ano \| findstr 8991` (Windows) or `lsof -i :8991` (Mac/Linux). Whitelist the Agent in your AV software.

OTA Updates and ESP32 Partition Schemes

One of the most powerful features of the Arduino Cloud Agent is managing Over-The-Air (OTA) updates for Wi-Fi-enabled boards like the Nano ESP32, Portenta C33, or generic ESP32-S3 dev boards. OTA allows the Agent to push compiled binaries over the local network without a physical USB connection.

However, OTA requires strict flash memory partitioning. The ESP32 flash must be divided to hold the bootloader, the Wi-Fi NVS data, and two identical application partitions (ota_0 and ota_1). If you are using a third-party ESP32 board and attempt an OTA flash via the Cloud Agent, and the board was previously flashed with a 'No OTA' or 'Minimal SPIFFS' partition table via the desktop IDE, the OTA update will fail with a Not enough space or Partition mismatch error.

The Fix: You must perform a one-time USB flash using the desktop Arduino IDE or the Cloud Agent in USB mode, explicitly selecting an OTA-compatible partition scheme in the Tools menu. Once the new partition table is written and the device connects to your Wi-Fi, the Arduino Cloud Agent will seamlessly route all subsequent updates over the air, freeing up your USB ports for new prototyping.