
Get up and running in minutes — download the firmware, flash your device using esptool, and boot straight into the web desktop environment.
Confirm you have everything in place before starting the flash process.
pip install esptool before proceeding to the flash step.Follow each step in order. Click a step to expand its instructions and commands.
Connect your ESP32-C5 to your host machine via USB-C. Identify the assigned serial port — on Linux/macOS it appears as /dev/ttyUSB0 or /dev/tty.SLAB_USBtoUART, on Windows as COM3 (or higher).
# Linux / macOS $ ls /dev/tty* # Windows (PowerShell) > Get-WMIObject Win32_SerialPort | Select DeviceID,Description
CP210x or CH340 USB driver if your device is not detected. Refer to your board's datasheet to confirm the UART chip.The ESP32-C5 must be in download mode to accept firmware. Hold the BOOT button, press and release RESET, then release BOOT. Alternatively, esptool can do this automatically via DTR/RTS.
# Verify device is in flash mode $ esptool.py --port /dev/ttyUSB0 chip_id
Chip is ESP32-C5. If you see a timeout, re-enter bootloader mode and try again.After flashing completes, the device resets automatically. terra-os will boot, broadcasting a Wi-Fi access point named terra-os-XXXXXX. Connect to it from any browser and navigate to http://192.168.4.1 to open the Web DE.
# Monitor serial output after boot $ esptool.py --port /dev/ttyUSB0 \ monitor --baud 115200
[terra-os] Web DE ready in the serial output confirming a successful boot.Expected output when flashing succeeds. Actual port and timing may vary.
Common issues and fixes for flashing terra-os to your ESP32-C5
If your ESP32-C5 is not showing up as a serial port, first check the USB-C cable — data-capable cables are required. Power-only cables will charge the board but will not expose a serial interface to your host machine.
Verify the device appears with the appropriate command for your OS:
Windows users: You may need to install the CP210x or CH340 USB-to-UART driver. Download from your board manufacturer's page and reboot after installation.
A timeout during flashing typically means esptool cannot communicate with the chip after connecting. The most common cause is that the ESP32-C5 is not in bootloader/download mode when the flash command runs.
Try lowering the baud rate to give the serial link more time to synchronise:
Tip: If the timeout persists, try a different USB port or a shorter USB cable. Long or low-quality cables introduce signal noise that can cause handshake failures.
The ESP32-C5 enters bootloader mode by holding the BOOT button while pressing and releasing RESET, then releasing BOOT. The sequence must be precise — releasing BOOT before the chip fully resets will cause it to boot normally instead of entering download mode.
Exact manual sequence:
Some boards with auto-reset circuitry (DTR/RTS lines) will enter bootloader mode automatically when esptool connects — no manual button press needed. Check your board's datasheet.
esptool will refuse to flash if it detects a chip family mismatch. The terra-os firmware image is compiled exclusively for ESP32-C5 and cannot run on ESP32, ESP32-S2, ESP32-S3, or ESP32-C3 variants.
Confirm your chip identity before flashing:
Do not override the chip check. Flashing incompatible firmware with --chip esp32c5 --no-check can brick your device and void any manufacturer warranty.
This happens when pip installs packages into a directory that is not on your system's PATH. The fix depends on your environment:
Recommended: Use a Python virtual environment (python3 -m venv .venv) to keep esptool isolated and avoid PATH conflicts with system Python packages.
After a successful flash, terra-os broadcasts a Wi-Fi access point named terra-os-XXXXXX (where XXXXXX is the last 6 digits of the device MAC address). If the AP does not appear within 15 seconds of boot, try the following:
Look for boot errors in the serial output. A partial flash (e.g., the bootloader wrote correctly but the application partition failed) will cause the device to reboot-loop silently.
Reboot-loop detected? Re-run the full flash command with the --erase-all flag to wipe the entire flash before writing. This clears any corrupted partition table from a previous partial flash.
A blank web interface at 192.168.4.1 usually means the frontend assets (HTML/CSS/JS) were not written to the SPIFFS/LittleFS partition, or the partition offsets in the flash command were incorrect.
The correct full flash command writes both the firmware and filesystem image:
Tip: The all-in-one terra-os-full.bin download from the Firmware page is pre-merged and can be flashed to 0x0 as a single file, eliminating partition offset errors entirely.
On macOS, USB serial devices appear as /dev/cu.usbserial-XXXX or /dev/cu.SLAB_USBtoUART — not /dev/ttyUSB0 as on Linux. Using the wrong device path is the most common macOS failure.
Additionally, macOS Ventura and later may require explicit permission to access serial devices. Check System Settings > Privacy & Security > Serial and ensure your terminal emulator is allowed.
Your ESP32-C5 is now running terra-os. Connect to the device's Wi-Fi AP and open the Web DE to start exploring features — or browse plugins and developer docs to make it your own.
Connect to the terra-os Wi-Fi AP and launch the web desktop environment to start exploring built-in features.
Extend terra-os with community plugins — network tools, serial utilities, and custom dashboards await.
Dive into the Plugin SDK and API reference to build your own tools and extensions for terra-os.
Default AP SSID: terra-os-setup · Web DE at 192.168.4.1 · No password required on first boot

terra-os is a flashable, web-based operating system that transforms your ESP32-C5 into a powerful, extensible platform — complete with a desktop environment, plugin ecosystem, and advanced network tools.
Explore the modules that power terra-os.
A sleek browser-based DE for full system control from any device.
Direct communication and debugging via serial console.
Extend terra-os with community and custom Python plugins.
Network deauthentication tools for authorized security testing.
Captive portal framework for network security assessments.
One-click firmware flashing with esptool compatibility.
Three steps from download to a fully working web desktop on your ESP32-C5.
Grab the latest terra-os firmware binary from the releases page. Lightweight at under 4 MB, optimized for the ESP32-C5 chipset.
Flash the firmware via USB using esptool or the terra-os web flasher. Full esptool compatibility means zero extra setup required.
Connect to your device's local network and open the hosted web desktop environment in any modern browser. You're live.
Powerful modules for authorized network security testing and research, built directly into terra-os.
Test the resilience of your wireless networks with the built-in deauthentication module. Identify vulnerable access points and evaluate your network's ability to withstand disconnection attacks in a controlled environment. Ideal for penetration testing workflows on hardware you own.
Deploy captive portal simulations to assess how users on your network respond to phishing-style login pages. The Evil Portal module lets you craft realistic portal interfaces for social engineering awareness training and security audits. Fully configurable templates included out of the box.
Use responsibly and only on networks you own or have permission to test.
terra-os ships with a Python-based Plugin SDK that makes it dead simple to browse, install, and build plugins for your ESP32-C5.
Use the CLI for quick installs or the Web Desktop plugin manager for a visual experience.
Leverage the Developer API and Plugin SDK to extend terra-os with custom modules. Built on a FastAPI backend, the platform gives you full access to device controls, serial communication, and the web desktop environment. Ship plugins that thousands of ESP32-C5 users can install in one click.
Hobbyists, developers, and researchers share their experience building with terra-os on the ESP32-C5.
Flashing terra-os onto my ESP32-C5 took under three minutes. The web desktop is incredibly responsive and the plugin ecosystem already has everything I need for my home automation projects.
The Plugin SDK is clean, well-documented, and makes extending terra-os a breeze. I built a custom network scanner plugin in an afternoon using the FastAPI backend hooks.
Finally, a proper OS for the ESP32-C5 that bundles deauth and evil portal tools responsibly. The serial interface for debugging is a game changer for network testing workflows.
Get terra-os running on your ESP32-C5 in under 5 minutes.
FreeOpen SourceNo account required
No comments yet. Be the first!