An embeddable operating system framework in Rust. Renders a skinnable shell interface -- scene-graph UI, command interpreter, virtual file system, browser engine, plugin system, remote terminal -- anywhere you can provide a pixel buffer and an input stream.

Dashboard	Terminal

Dashboard	Terminal

Dashboard	Terminal

Dashboard	Terminal

Terminal	Tactical	Corrupted	Agent Terminal

OASIS_OS originated as a Rust port of a PSP homebrew shell OS written in C circa 2006-2008. The trait-based backend system designed for cross-platform portability extends to four rendering targets:

The framework supports a data-driven skin system that controls visual layout, color themes, feature gating, and behavioral personality. Skins are defined in TOML configuration files -- no code changes required. Eight skins are implemented:

All skins share the same core: scene graph, command interpreter, virtual file system, networking, and plugin infrastructure. See the Skin Authoring Guide for creating custom skins.

Native virtual resolution is 480x272 (PSP native) across all backends.

• Scene Graph (SDI) -- Named object registry with position, size, color, texture, text, z-order, alpha, gradients, rounded corners, shadows
• Browser Engine -- Embedded HTML/CSS/Gemini renderer with DOM parsing, CSS cascade, block/inline/table layout, link navigation, reader mode, bookmarks
• Window Manager -- Movable, resizable, overlapping windows with titlebars, minimize/maximize/close, hit testing, and themed decorations
• UI Widget Toolkit -- 20+ reusable widgets: Button, Card, TabBar, Panel, TextField, ListView, ScrollView, ProgressBar, Toggle, NinePatch, flex layout, and more
• Proportional Bitmap Font -- Variable-width glyph rendering from ink bounds with per-character advance values (not fixed-width 8x8)
• 90+ Terminal Commands -- 17 command modules: core (fs/system), text processing (head, tail, grep, sort, uniq, tr, cut, diff), file utilities (write, tree, du, stat, xxd, checksum), dev tools (base64, json, uuid, seq, expr), fun (cal, fortune, banner, matrix), security (chmod, chown, passwd, audit), documentation (man, tutorial, motd), networking (wifi, ping, http), audio, UI, skin switching, scripting, transfer (FTP), system updates. Shell features include variable expansion, glob expansion, aliases, history (!!/!n), piping, and command chaining
• Audio System -- Playlist management, MP3/WAV playback, ID3 tag parsing, shuffle/repeat modes, volume control
• Plugin System -- Runtime-extensible via Plugin trait, VFS-based IPC, manifest-driven discovery
• Virtual File System -- MemoryVfs (in-RAM), RealVfs (disk), GameAssetVfs (UE5 with overlay writes)
• Remote Terminal -- TCP listener with PSK authentication for headless device management
• Agent/MCP Integration -- Agent status tracking, MCP tool browsing/invocation, tamper detection, system health dashboard
• Scripting -- Line-based command scripts, startup scripts, cron-like scheduling
• 8 Built-in Apps -- File Manager (dual-panel Norton Commander-style), Settings, Network, Music Player, Photo Viewer, Package Manager, Browser, System Monitor

The framework is split into 16 workspace crates plus 2 excluded PSP crates:

oasis-os/
+-- Cargo.toml                        # Workspace root (resolver="2", edition 2024)
+-- crates/
|   +-- oasis-types/                  # Foundation types: Color, Button, InputEvent, backend traits, error types
|   +-- oasis-vfs/                    # Virtual file system: MemoryVfs, RealVfs, GameAssetVfs
|   +-- oasis-platform/              # Platform service traits: Power, Time, USB, Network, OSK
|   +-- oasis-sdi/                    # Scene Display Interface: named object registry, z-order, rendering
|   +-- oasis-net/                    # TCP networking, PSK authentication, remote terminal, FTP transfer
|   +-- oasis-audio/                  # Audio manager, playlist, shuffle/repeat, MP3 ID3 parsing
|   +-- oasis-ui/                     # 20+ widgets: Button, Card, TabBar, Panel, TextField, ListView, etc.
|   +-- oasis-wm/                     # Window manager: drag/resize, hit testing, minimize/maximize/close
|   +-- oasis-skin/                   # TOML skin engine, 8 skins, theme derivation from 9 base colors
|   +-- oasis-terminal/              # Command interpreter: 90+ commands across 17 modules, shell features
|   +-- oasis-browser/               # HTML/CSS/Gemini browser: DOM, CSS cascade, block/inline/table layout
|   +-- oasis-core/                   # Coordination layer: apps, dashboard, agent, plugin, script, etc.
|   +-- oasis-backend-sdl/            # SDL2 rendering and input (desktop + Pi)
|   +-- oasis-backend-ue5/            # UE5 software framebuffer + FFI input queue
|   +-- oasis-backend-psp/            # [excluded from workspace] sceGu hardware rendering, PSP controller, UMD browsing
|   +-- oasis-plugin-psp/            # [excluded from workspace] kernel-mode PRX: in-game overlay + background music
|   +-- oasis-ffi/                    # C FFI boundary for UE5 integration
|   +-- oasis-app/                    # Binary entry points: desktop app + screenshot tool
+-- skins/
|   +-- classic/                      # PSIX-style icon grid dashboard
|   +-- xp/                           # Windows XP Luna-inspired theme with start menu
+-- docs/
    +-- design.md                     # Technical design document (v2.4)
    +-- skin-authoring.md             # Skin creation guide with full TOML reference
    +-- psp-modernization-plan.md     # PSP backend modernization roadmap (9 phases, 40 steps)

The PSP crates are excluded from the workspace (require mipsel-sony-psp target) and depend on the standalone rust-psp SDK via git dependency. The backend compiles to an EBOOT.PBP (standalone application), while the plugin compiles to a kernel-mode PRX (resident overlay module loaded by CFW via PLUGINS.TXT).

# Via Docker (container-first)
docker compose --profile ci run --rm rust-ci cargo build --release -p oasis-app

# Or natively (requires libsdl2-dev, libsdl2-mixer-dev)
cargo build --release -p oasis-app

Requires the nightly Rust toolchain with rust-src and cargo-psp:

cd crates/oasis-backend-psp
RUST_PSP_BUILD_STD=1 cargo +nightly psp --release
# Output: target/mipsel-sony-psp-std/release/EBOOT.PBP

cd crates/oasis-plugin-psp
RUST_PSP_BUILD_STD=1 cargo +nightly psp --release
# Output: target/mipsel-sony-psp-std/release/oasis-plugin-psp.prx

See PSP Plugin Guide for installation and usage.

cargo build --release -p oasis-ffi
# Output: target/release/liboasis_ffi.so (or .dll on Windows)

Capture screenshots for all skins:

# Classic skin (default)
cargo run -p oasis-app --bin oasis-screenshot

# Any skin by name
cargo run -p oasis-app --bin oasis-screenshot xp
cargo run -p oasis-app --bin oasis-screenshot modern
cargo run -p oasis-app --bin oasis-screenshot desktop
cargo run -p oasis-app --bin oasis-screenshot terminal
cargo run -p oasis-app --bin oasis-screenshot tactical
cargo run -p oasis-app --bin oasis-screenshot corrupted
cargo run -p oasis-app --bin oasis-screenshot agent-terminal

The repo includes a containerized PPSSPP emulator with NVIDIA GPU passthrough for testing PSP EBOOTs:

# Build the PPSSPP Docker image (first time only)
docker compose --profile psp build ppsspp

# Run with GUI (requires X11 display)
docker compose --profile psp run --rm ppsspp /roms/release/EBOOT.PBP

# Run headless (CI / no display -- exits TIMEOUT on success)
docker compose --profile psp run --rm -e PPSSPP_HEADLESS=1 ppsspp /roms/release/EBOOT.PBP --timeout=5

# Run with interpreter (more stable for some MIPS code paths)
docker compose --profile psp run --rm -e PPSSPP_HEADLESS=1 ppsspp /roms/release/EBOOT.PBP -i --timeout=5

The /roms/ mount maps to crates/oasis-backend-psp/target/mipsel-sony-psp-std/ so both release/ and debug/ EBOOTs are available. Headless mode exits with TIMEOUT on success (OASIS_OS runs an infinite render loop). Any crash produces a non-zero exit code.

All CI stages run in Docker containers on a self-hosted runner:

# Build the CI container
docker compose --profile ci build

# Format check
docker compose --profile ci run --rm rust-ci cargo fmt --all -- --check

# Clippy
docker compose --profile ci run --rm rust-ci cargo clippy --workspace -- -D warnings

# Tests
docker compose --profile ci run --rm rust-ci cargo test --workspace

# License/advisory check
docker compose --profile ci run --rm rust-ci cargo deny check

GitHub Actions workflows run the full pipeline automatically on push to main and on pull requests, including PSP EBOOT build + PPSSPP headless testing, AI code review (Gemini + Codex), and automated fix agents.

• Technical Design Document -- architecture, backends, skins, UE5 integration, PSP implementation, VFS, plugin system, security considerations, migration strategy (v2.4, 1300+ lines)
• Skin Authoring Guide -- creating custom skins, TOML file reference, theme derivation, effect system, runtime switching
• PSP Modernization Plan -- 9-phase, 40-step roadmap for PSP backend modernization using the rust-psp SDK
• PSP Plugin Guide -- installation, controls, and configuration for the in-game overlay PRX

Dual-licensed under MIT and Unlicense.