Framely

简体中文

Framely is still under rapid development. Features and interfaces may change between preview releases. Android app and game compatibility depends on Lepton and the app itself.

Framely provides a unified spatial launcher for Steam Frame and a management panel available both inside the headset and in a PC browser.

• Unified launcher: launch Android apps in Lepton, Linux desktop applications, local Steam games, and games available through Steam Remote Play.
• APK sideloading and management: install, update, and uninstall APKs, manage application containers and data, and provide controller input mapping and rumble feedback for Android games that support controllers.
• Plugin installation and management: install and manage Framely plugins, browse the plugin library, and extend Frame with additional features.
• Remote management from your PC: access Frame's management panel in a PC browser to manage files, APKs, and plugins. Upload, download, and edit files, and preview common image and video formats.
• Web terminal: use an interactive terminal running on Frame, execute shell commands, and connect to other devices with ssh. The web terminal does not require an SSH connection to Frame.

Framely uses a Rust core service and a separate CEF/OpenVR host, with a desktop installer for setup. It also manages plugin sources, windows, notifications, and updates.

Installation

The target device is a Linux ARM64 Steam Frame. Enable developer mode and SSH on Frame, connect your computer and Frame to the same network, and prepare the steamos account password.

Desktop installer

Download the package for your computer from the Framely Installer release. Linux packages are .tar.gz; Windows and macOS packages are .zip. Extract and launch the installer, enter the Frame IP and SSH port, verify the SSH fingerprint, and connect with the steamos account. Select the Framely version, then confirm installation. Enable testing releases to install a Preview version. Installer and device versions are independent.

Command installation

Run the following command in Frame's SSH terminal to install the latest stable release:

curl -fsSL https://raw.githubusercontent.com/SteamFramelyHomebrew/framely/main/install.sh | bash -s -- install

For a Preview release, specify an actual published tag:

curl -fsSL https://raw.githubusercontent.com/SteamFramelyHomebrew/framely/main/install.sh | bash -s -- install --version v0.4.5-preview.2

Replace the example tag with the published version you want to install. Enter the sudo password when prompted. See the installation guide for updates, repair, and uninstallation.

First installation uses the complete offline package with CEF; updates use the smaller core package and reuse CEF; the device needs neither Node.js nor Rust. Installation requests sudo and does not automatically disable SteamOS read-only protection. Click the Framely Dock icon in the SteamVR Dashboard to open the launcher, or hold it for 600 ms to open the quick panel; a border progress indicator appears while holding. Open the manager from the launcher’s Settings button.

The network panel uses port 15915 by default. Visit http://DEVICE_IP:15915 on your phone or computer. When no password is configured, the first visit requires setting and confirming a password before login. The device password and panel password are independent.

Documentation

Start at the documentation index:

• Install, update, repair, roll back, and uninstall
• Basic usage · Install and manage plugins
• APK Manager · Space launcher
• Network management panel
• Plugin development through publishing · Publish plugins and sources
• SDK API · Manifest configuration · Lifecycle
• Plugin template · Showcase example
• Core release maintenance · Build the installer

Create a plugin

Install Node.js 22 and npm on your development computer, clone this repository, and run:

node tools/plugin-dev.mjs init ../my-plugin yourname.my-plugin
cd ../my-plugin
npm install
npm run dev
npm run build

The generated project includes React pages, a Python backend, persistent storage, lifecycle callbacks, the SDK, and build tools. Browser preview does not start the backend; see the development guide for packaging and testing on Frame.

Build and validate

Building the core from source requires Linux, Rust, Node.js, C/C++, and OpenGL/X11 development libraries. The production native host uses the pinned Linux ARM64 CEF version.

npm ci
npm run typecheck
npm run build
cargo test --locked
bash tools/test-native.sh
python3 -m unittest discover -s tests -p 'test_*.py'

See release maintenance for CEF builds, integration tests, and publishing commands. Plugins support steamos and root; hash verification is not a security review, so check the source and runtime user.

License

Original Framely code, including the core, installer, SDK, template, and repository examples, uses AGPL-3.0-only; see LICENSE. Third-party dependencies and vendored files retain their respective licenses.

AGPL allows commercial use. Distribution requires complete corresponding source under the license; modified software that interacts with users over a network must also offer source to those users. Release source corresponds to the repository's v<VERSION> or installer-v<VERSION> tags. Redistributors must provide modifications and build scripts matching their binaries.