ionChannel

Modern Remote Desktop Portal for Wayland Compositors

A production-ready remote desktop solution that provides secure, low-latency access to Wayland desktop sessions through capability-based backend discovery and runtime configuration.

🚀 Quick Start

Prerequisites

Ubuntu 22.04+ or similar Linux distribution
Rust 1.75+
libvirt (for VM demos)

Build

cargo build --workspace --all-features

Run Tests

cargo test --workspace

Run Demo

./RUN_DEMO.sh

See QUICK_START.md for the fastest way to get started!

Detailed instructions: QUICKSTART.md

📖 Documentation

Getting Started

QUICK_START.md ⭐ - Fastest way to get started!
AUTONOMOUS_PROVISIONING.md 🤖 - Zero-human-interaction VM provisioning
QUICKSTART.md - Detailed build and run instructions
STATUS.md - Current project status and metrics
PROJECT_COMPLETION_SUMMARY.md - Complete project overview

Demonstrations

DEMO_GUIDE.md - Complete demo guide with troubleshooting

Architecture

CAPABILITY_BASED_VM_DISCOVERY.md - Primal discovery patterns
BENCHSCALE_INTEGRATION.md - benchScale v2.0.0 integration
SCREEN_CAPTURE_PIPEWIRE.md - PipeWire-first capture architecture

Testing

docs/testing/ - Test plans and results
docs/reports/ - Historical session reports

Reference

DOCUMENTATION_INDEX.md - Complete documentation index
NEXT_STEPS.md - Future enhancements

🎯 Features

Core Capabilities

✅ Wayland Native - Full support for modern compositors (COSMIC, Sway, etc.)
✅ Zero Hardcoding - All configuration via runtime discovery
✅ Capability-Based Discovery - Runtime backend selection
✅ Primal Philosophy - Self-knowledge only, discover at runtime
✅ Production Ready - Zero technical debt, zero unsafe code
✅ Modern Rust - Async/await, clippy-clean, idiomatic patterns

Backend Support

COSMIC Compositor - Full integration with System76's COSMIC
Generic Wayland - Works with any wlroots-based compositor
Extensible - Easy to add new backends via traits

Validation Framework

VM Provisioning - Automated VM creation via benchScale
Remote Desktop - RustDesk installation and configuration
Portal Deployment - Complete ionChannel build and deployment
E2E Verification - Health checks and integration tests
Event Streaming - Full observability for AI agents

🏗️ Architecture

Primal Philosophy

ionChannel follows "primal philosophy":

Self-Knowledge Only - Code only knows about itself
Runtime Discovery - Find other components at runtime
Capability-Based - Select by capability, not name
Environment-Driven - Zero hardcoded configuration

Trait-Based Abstractions

// Backends discovered at runtime
trait DesktopBackend {
    async fn is_available(&self) -> bool;
    fn capabilities(&self) -> BackendCapabilities;
    async fn inject_input(&self, event: InputEvent) -> Result<()>;
    async fn capture_screen(&self) -> Result<Frame>;
}

// VM backends discovered at runtime
trait VmBackendProvider {
    async fn is_available(&self) -> bool;
    fn capabilities(&self) -> Vec<VmCapability>;
    async fn create_provisioner(&self) -> Result<Arc<dyn VmProvisioner>>;
}

Zero Unsafe Code

All crates explicitly forbid unsafe code:

#![forbid(unsafe_code)]

📊 Status

Production Ready - December 27, 2025

Quality Metrics

Tests: 11/11 passing ✅
Unsafe Code: 0 ✅
TODOs: 0 in production ✅
Mocks: 0 in production ✅
Hardcoded Values: 0 ✅

Implementation

Crates: 9 production crates
Lines of Code: ~15,000
Documentation: 20 files
Examples: 6 runnable demos
Test Coverage: Comprehensive unit + integration

See STATUS.md for detailed metrics.

🎮 Demos

1. Full E2E Validation (Recommended)

./RUN_DEMO.sh

Shows: Discovery → Provisioning → Installation → Deployment → Verification

2. Capability Discovery

cargo run -p ion-validation --example discover_and_provision --features libvirt

Shows: Runtime backend discovery with capability queries

3. Quick VM Test

cargo run -p ion-validation --example create_working_vm --features libvirt

Shows: Basic VM provisioning and SSH verification

See DEMO_GUIDE.md for all demo options.

🧪 Testing

Run All Tests

cargo test --workspace

Run Test Suite

./TEST_SUITE.sh

Run Specific Crate

cargo test -p ion-validation --features libvirt

🔧 Configuration

All configuration via environment variables (zero hardcoding):

VM Configuration

export VM_SSH_USER="ubuntu"
export VM_SSH_PASSWORD="ubuntu"
export BENCHSCALE_LIBVIRT_URI="qemu:///system"

RustDesk Configuration

export RUSTDESK_VERSION="1.2.3"
export RUSTDESK_DOWNLOAD_URL="https://github.com/rustdesk/rustdesk/releases/..."

ionChannel Deployment

export IONCHANNEL_REPO_URL="https://github.com/YourOrg/ionChannel.git"
export BUILD_RELEASE="false"

See DEMO_GUIDE.md for complete configuration reference.

📦 Project Structure

ionChannel/
├── crates/
│   ├── ion-core/           # Core backend discovery
│   ├── ion-traits/         # Shared trait definitions
│   ├── ion-portal/         # Desktop portal service
│   ├── ion-compositor/     # Compositor integration
│   ├── ion-backend-cosmic/ # COSMIC backend
│   ├── ion-backend-wayland/# Generic Wayland backend
│   ├── ion-validation/     # E2E validation framework
│   ├── ion-deploy/         # Deployment tools
│   └── ion-test-substrate/ # Test utilities
├── benches/                # Performance benchmarks
├── docs/                   # Detailed documentation
│   └── reports/            # Session reports
├── specs/                  # Specifications
└── examples/               # Usage examples

🤝 Contributing

ionChannel follows strict principles:

No Unsafe Code - All crates forbid unsafe
No Hardcoding - All config from environment
No Mocks in Production - Complete implementations only
Primal Philosophy - Runtime discovery, capability-based
Modern Rust - Async/await, traits, Result-based errors

📄 License

Dual-licensed under Apache 2.0 or MIT.

See LICENSE-APACHE and LICENSE-MIT for details.

🙏 Acknowledgments

Built with:

COSMIC - Modern Wayland compositor
benchScale - VM management framework
RustDesk - Open source remote desktop

📞 Quick Reference

Main Documentation: FINAL_STATUS_COMPLETE.md
Demo Guide: DEMO_GUIDE.md
Current Status: STATUS.md
Quick Start: QUICKSTART.md

Run ./RUN_DEMO.sh to see it in action! 🚀

FilesExpand file tree

README.md

Latest commit

History