terra-os
Fifhdvdy LastnameA super nice OS for my ESP32-C5 supporting a web DE/interface and serial interface, with deuathentication and evil portal functions, and a ton of other nice things.
Comments (0)
Sign in to leave a comment
Project Tasks18
Implement Theme & Color System
As a developer, I want a unified color theme and typography system applied across all scaffold pages so that the application visually aligns with the SRD brand guidelines (Deep Blue #003366, Light Cyan #00BFFF, Soft Gray #F5F5F5, Vibrant Orange #FF6600, Roboto/Open Sans). Remove unneeded scaffold pages (login, signup, welcome, dashboard/overview, dashboard/ai-assistant, dashboard/settings). This task must be completed first and remain independent of all other tasks.
Implement Landing Page
As a hobbyist or developer visiting terra-os, I want to see an engaging landing page with a dynamic animated circuit board so that I immediately understand the product and am motivated to explore firmware flashing or the Web DE. Implement based on the existing Landing (v2) JSX design with animated circuit board traces, hover glow effects, ripple interactions, and time-of-day color shifts. Links to Flash Guide and Web DE pages.
Implement Web DE Page
As a developer or hobbyist, I want to access a web-based desktop environment page so that I can launch and interact with the terra-os desktop interface from my browser. Implement based on the existing Web DE (v2) JSX design. Links from Landing and Flash Guide; connects to Plugins, Network Tools, Serial Interface, Plugin SDK, and the AI assistant.
Implement Flash Guide Page
As a hobbyist, I want a clear flash guide page so that I can download the correct firmware and follow step-by-step instructions to flash my ESP32-C5 device successfully. Implement based on the existing Flash Guide (v2) JSX design. Reached from the Landing page, leads to the Web DE.
Implement Plugins Page
As a hobbyist or developer, I want to browse, install, upload, and test plugins from a dedicated plugins page so that I can extend the functionality of my terra-os device. Implement based on the existing Plugins (v2) JSX design. Accessible from the Web DE.
Implement Network Tools Page
As a hobbyist, I want a network tools page with deauthentication and evil portal controls so that I can run network operations directly from the terra-os web interface. Implement based on the existing Network Tools (v2) JSX design. Accessible from the Web DE.
Implement Serial Interface Page
As a developer, I want a serial interface page so that I can view debug output and communicate with my ESP32-C5 device over a serial connection from the browser. Implement based on the existing Serial Interface (v2) JSX design. Accessible from the Web DE; serves as the final debug step in the developer flow.
Implement Plugin SDK Page
As a developer, I want a plugin SDK page with API documentation and plugin creation guidance so that I can build and test Python-based plugins for terra-os. Implement based on the existing Plugin SDK (v2) JSX design. Accessible from the Web DE; leads to the Plugins page for uploading created plugins.
Build Firmware Flash API
As a hobbyist, I want backend endpoints that serve firmware download links and flash guide metadata so that I can retrieve the correct firmware version and step-by-step instructions for my ESP32-C5 device.
Integrate GPT 5.2 AI Assistant
As a user of the Web DE, I want an AI assistant powered by GPT 5.2 so that I can receive intelligent, user-friendly responses to queries about my terra-os device and plugins directly within the desktop environment.
Build Plugin Management API
As a backend system, I want CRUD endpoints for plugin upload, listing, installation, and testing so that the frontend can manage Python-based plugins and developers can publish new plugins to the platform. Includes plugin metadata storage in MySQL.
Build Network Tools API
As a backend system, I want API endpoints for deauthentication and evil portal operations so that the frontend network tools page can trigger and monitor these functions on connected ESP32-C5 devices. Must include authentication checks for sensitive operations.
Build Serial Interface API
As a backend system, I want serial communication endpoints so that the frontend serial interface page can establish, read from, and write to a serial connection with the ESP32-C5 device in real time via WebSocket or polling.
Build Plugin SDK API
As a developer, I want API endpoints that expose SDK documentation content and validate plugin packages so that I can programmatically access API docs and verify plugins before publishing to the plugin registry.
Connect Plugins to API
As a hobbyist or developer, I want the plugins page connected to the Plugin Management API so that I can browse, install, upload, and test plugins with live data from the backend.
Connect Network Tools to API
As a hobbyist, I want the network tools page integrated with the Network Tools API so that deauthentication and evil portal operations are triggered and monitored in real time from the browser.
Connect Serial Interface to API
As a developer, I want the serial interface page connected to the Serial Interface API so that I can send commands and view live debug output from my ESP32-C5 device in the browser.
Connect Web DE to Backend
As a developer or hobbyist using the Web DE, I want the desktop environment page wired to backend APIs and the AI assistant so that all Web DE features including plugin management and AI responses are fully functional with live data.
Your ESP32-C5. Fully Unleashed.
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.
Everything Wired In.
Explore the modules that power terra-os.
Web Desktop Environment
A sleek browser-based DE for full system control from any device.
Serial Interface
Direct communication and debugging via serial console.
Plugin System
Extend terra-os with community and custom Python plugins.
Deauth Package
Network deauthentication tools for authorized security testing.
Evil Portal
Captive portal framework for network security assessments.
Flash Utility
One-click firmware flashing with esptool compatibility.
Up and Running in Minutes
Three steps from download to a fully working web desktop on your ESP32-C5.
Download Firmware
Grab the latest terra-os firmware binary from the releases page. Lightweight at under 4 MB, optimized for the ESP32-C5 chipset.
Flash to ESP32-C5
Flash the firmware via USB using esptool or the terra-os web flasher. Full esptool compatibility means zero extra setup required.
Launch Web DE
Connect to your device's local network and open the hosted web desktop environment in any modern browser. You're live.
Advanced Network Tools
Powerful modules for authorized network security testing and research, built directly into terra-os.
Deauth Package
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.
Evil Portal
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.
Extend Everything with Plugins.
terra-os ships with a Python-based Plugin SDK that makes it dead simple to browse, install, and build plugins for your ESP32-C5.
Browse Plugins
Install in One Click
Use the CLI for quick installs or the Web Desktop plugin manager for a visual experience.
Build Your Own
- ✓Python-based SDK — write plugins in familiar Python syntax
- ✓Hot Reload — push changes without reflashing firmware
- ✓Web DE Widgets — create custom desktop panels and windows
- ✓Hardware API — direct GPIO, SPI, and I2C access helpers
- ✓Event System — hook into OS lifecycle and network events
- ✓Publish to Registry — share plugins with the community in one command
Build for terra-os
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.
What the Community Says
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.
Ready to Flash?
Get terra-os running on your ESP32-C5 in under 5 minutes.
FreeOpen SourceNo account required
No comments yet. Be the first!