EcoOS is a purpose-built Ubuntu-based operating system for EcoBridge kiosks and local device appliances. It boots into a fullscreen bundled EcoBridge Main App under Sway while the EcoOS daemon exposes a management UI and API on 0.0.0.0:3006.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Features

Mainapp kiosk boot - Sway starts the bundled EcoBridge Main App from /opt/eco/mainapp/current/ecobridge.xyz.
Management UI - Monitoring and control via HTTP on port 3006.
Signed mainapp updates - The daemon verifies a signed manifest before installing or switching mainapp releases.
EcoOS daemon updates - The daemon can check and apply EcoOS release upgrades.
System monitoring - CPU, memory, disk, network, GPU, input, audio, logs, and service health.
Display controls - Sway output discovery and display enable/disable/primary actions.
Compatibility endpoint - /api/restart-chromium remains available as an alias for shipped clients, but the runtime app is now the mainapp.

Architecture

EcoOS ISO / installed system
├── eco-daemon (systemd)
│   ├── process manager: Sway + EcoBridge Main App
│   ├── system info collector
│   ├── EcoOS updater
│   ├── signed mainapp updater
│   └── UI server: REST API and dashboard on 0.0.0.0:3006
├── Sway compositor (Wayland)
│   └── EcoBridge Main App (fullscreen Electron app)
├── /opt/eco/mainapp/releases/<version>
├── /opt/eco/mainapp/current -> active release
└── Ubuntu 24.04 base with systemd, seatd, and PipeWire

Development

Prerequisites

Docker for ISO building
pnpm for package scripts
Deno v2.x for daemon development
QEMU for ISO testing

Project Structure

eco_os/
├── ecoos_daemon/          # Daemon source (Deno/TypeScript)
│   ├── mod.ts             # Entry point
│   ├── keys/              # Public keys used for update verification
│   ├── ts/daemon/         # Core daemon, process manager, updaters
│   ├── ts/ui/             # HTTP/WebSocket management server
│   ├── ts_interfaces/     # API contracts shared with the UI
│   └── ts_web/            # Management UI frontend
├── isobuild/              # ISO build configuration
│   ├── Dockerfile         # Build container and ISO assembly
│   ├── mainapp-version.txt # Bundled mainapp release tag
│   ├── config/            # live-build configuration
│   └── scripts/           # Build scripts
├── isotest/               # QEMU test scripts
└── .nogit/                # Generated artifacts and local secrets

Commands

# Build the amd64 ISO. The build also rebuilds the daemon UI bundle.
pnpm run build

# Explicit amd64 build.
pnpm run build:amd64

# Type-check daemon code.
pnpm run daemon:typecheck

# Build the management UI bundle.
pnpm run daemon:ui

# Bundle daemon to a standalone binary.
pnpm run daemon:bundle

# Test ISO in QEMU.
pnpm run test

# Take a screenshot of the running VM.
pnpm run test:screenshot

# Stop the QEMU VM.
pnpm run test:stop

# Clean generated build artifacts.
pnpm run clean

Current bundled mainapp support is amd64 / Linux x64 only. The arm64 and rpi build scripts remain present but are intentionally blocked until matching signed mainapp release artifacts exist.

Management UI and API

The daemon serves the management UI at http://localhost:3006 and on the device IP at port 3006.

Dashboard Panels

Panel	Description
Services	Sway and Main App status
CPU	Model, core count, and real-time usage
Memory	Used and total memory
Network	Interface names and IP addresses
Disks	Mount points, usage, and capacity
System	Hostname, uptime, and GPU information
Controls	Mainapp restart, display controls, and system reboot
Updates	EcoOS daemon update controls and signed mainapp update controls
Input Devices	Keyboards, mice, touchscreens, and related devices
Audio	Detected speakers and microphones
Logs	Daemon logs and system journal output

API Endpoints

Endpoint	Method	Description	Privileged
`/api/status`	GET	Full system status	No
`/api/logs`	GET	Daemon logs	No
`/api/displays`	GET	Sway display information	No
`/api/reboot`	POST	Reboot the system	Yes
`/api/restart-mainapp`	POST	Restart the EcoBridge Main App	Yes
`/api/restart-chromium`	POST	Compatibility alias for restarting the mainapp	Yes
`/api/updates`	GET	EcoOS update information	No
`/api/updates/check`	POST	Check for EcoOS updates	Yes
`/api/upgrade`	POST	Upgrade EcoOS to a specific version	Yes
`/api/mainapp-updates`	GET	Signed mainapp update information	No
`/api/mainapp-updates/check`	POST	Check for signed mainapp updates	Yes
`/api/mainapp-upgrade`	POST	Install and switch to a specific mainapp version	Yes
`/api/displays/{name}/enable`	POST	Enable a display output	Yes
`/api/displays/{name}/disable`	POST	Disable a display output	Yes
`/api/displays/{name}/primary`	POST	Set the primary kiosk display	Yes
`/ws`	WebSocket	WebSocket connection endpoint	No

Privileged endpoints accept loopback requests automatically. Remote requests must provide ECOOS_API_TOKEN either as Authorization: Bearer <token> or X-EcoOS-Api-Token: <token>.

Update System

EcoOS has two update tracks.

EcoOS Daemon Updates

The daemon polls EcoOS releases and tracks available versions.
New EcoOS releases wait through a stability period before automatic upgrade.
Manual checks and upgrades are available through the UI and API.
The UI reloads when the daemon version changes.

Signed Mainapp Updates

Mainapp releases are discovered from ecobridge.xyz/mainapp Gitea releases.
EcoOS only accepts releases with mainapp-update-manifest.json and mainapp-update-manifest.json.sig.
The manifest signature is verified with the pinned public key in ecoos_daemon/keys/.
The manifest must match the expected app id, channel, architecture, version, asset size, and SHA256.
The portable tarball is extracted safely into /opt/eco/mainapp/releases/<version>.
/opt/eco/mainapp/current is switched only after verification.
The daemon restarts the mainapp, performs a health check, and rolls back on failure.

The bundled mainapp version for ISO builds is pinned in isobuild/mainapp-version.txt.

Testing

QEMU Virtual Machine

# Start VM.
pnpm run test

# Take screenshots to monitor progress.
pnpm run test:screenshot

# Screenshot loop.
pnpm run test:screenshot:loop

# Stop VM.
pnpm run test:stop

# Clean and restart fresh.
pnpm run test:clean && pnpm run test

Serial Console

socat - UNIX-CONNECT:.nogit/vm/serial.sock

Release Assets

EcoOS releases include the bootable ISO, standalone daemon binary for in-place upgrades, and SHA256 checksums.

The ISO build consumes a signed mainapp release from the mainapp repository. The expected portable asset name is EcoBridge-MainApp-vX.X.X-linux-x64.tar.gz, with the release tag read from isobuild/mainapp-version.txt.

Install EcoOS - Full installation to disk, auto-selected by default.
EcoOS Live - Try without installing, running from RAM.
EcoOS Live Safe Mode - Minimal boot for troubleshooting.

Technical Details

Daemon

Runtime: Deno compiled to a standalone binary for the ISO.
Process management: Spawns and monitors Sway and the EcoBridge Main App.
Backend fallback: Tries DRM first and falls back to headless or software-rendered modes when needed.
Auto-recovery: Restarts crashed services.
Logging: Integrates with the systemd journal and management UI.

Mainapp Runtime

Executable: /opt/eco/mainapp/current/ecobridge.xyz.
Environment: RUNTIME_ENV=sway.
Electron flags: --no-sandbox, --ozone-platform=wayland, --enable-features=UseOzonePlatform, and --disable-dev-shm-usage.
Active release link: /opt/eco/mainapp/current.
Release storage: /opt/eco/mainapp/releases/<version>.

System Stack

Base: Ubuntu 24.04 LTS.
Init: systemd.
Display: Sway Wayland compositor.
Seat manager: seatd.
Audio: PipeWire.

License and Legal Information

No dedicated repository license file is currently present. Confirm the licensing terms before public redistribution.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

EcoOS