
A Python-first SDK built on FastAPI. Define lifecycle hooks, register event listeners, and expose REST endpoints — all from a single class. Ship your plugin, let terra-os handle the rest.
Master these four foundational concepts to build reliable, secure, and well-integrated plugins for the terra-os ecosystem.
Every terra-os plugin declares its identity, dependencies, and capabilities in a structured manifest.json file. The manifest defines the plugin name, version, required permissions, and entry point — allowing the OS to validate and load plugins safely at runtime.
Learn more→Plugins interact with the terra-os runtime through a set of well-defined lifecycle hooks: on_install, on_init, on_start, on_stop, and on_uninstall. Each hook gives your plugin a precise moment to allocate resources, register handlers, or clean up state gracefully.
Learn more→The terra-os Event Bus provides a lightweight publish-subscribe messaging layer between plugins and the core OS. Plugins can emit custom events, subscribe to system events (wifi.connected, serial.data, plugin.loaded), and communicate without tight coupling.
Learn more→terra-os enforces a capability-based permissions model to keep the device secure. Plugins must declare required permissions (e.g., network.access, serial.read, wifi.scan) in their manifest, and users approve them at install time — mirroring familiar mobile OS security patterns.
Learn more→Complete reference for the terra-sdk Python API. Click any row to expand full documentation.
| Name | Signature | Description | Since | |
|---|---|---|---|---|
| register_plugin | register_plugin(manifest: PluginManifest) -> bool | Registers a plugin with the terra-os runtime. Returns True on success. | v1.0.0 | |
| emit_event | emit_event(event: str, payload: dict) -> None | Publishes an event to the terra-os event bus. All subscribed handlers receive the payload. | v1.0.0 | |
| get_config | get_config(key: str, default: Any = None) -> Any | Retrieves a plugin configuration value from persistent NVS storage. | v1.0.0 | |
| set_config | set_config(key: str, value: Any) -> None | Persists a plugin configuration value to NVS storage across reboots. | v1.0.0 | |
| log | log(level: str, message: str) -> None | Writes a structured log entry to the terra-os system log and serial output. | v1.0.0 | |
| expose_endpoint | expose_endpoint(path: str, handler: Callable, method: str = "GET") -> None | Registers a FastAPI route on the terra-os web server under the plugin's namespace. | v1.1.0 |
Every terra-os plugin transitions through six phases. Hover any node to inspect the phase description and its corresponding lifecycle hook.
Plugin SDK
Practical, copy-ready Python examples covering the core terra-os plugin patterns. Click a tab to explore each pattern with annotated callouts.
Annotations
The terra-sdk gives you everything you need to build, test, and deploy plugins for the ESP32-C5. Includes FastAPI scaffolding, lifecycle hooks, event bus access, and full API documentation.
terra-os is built by hobbyists, for hobbyists. Ask questions, share your plugins, and help shape the platform.
Ask questions, share ideas, and get help from the terra-os community and maintainers. Browse open threads or start a new discussion about plugin development, hardware quirks, or OS internals.
Join the discussionHang out in real-time with other terra-os hobbyists and developers. Get instant help in #plugin-dev, share builds in #showcase, and stay updated with #announcements.
Join Discord serverFound an issue with the Plugin SDK, lifecycle hooks, or the terra-os runtime? Open a GitHub Issue with reproduction steps, firmware version, and your plugin manifest so maintainers can triage fast.
Open an issueCheck the Wiki and Changelog before filing — your question may already be answered.

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!