mirror of
https://github.com/saphid/frame-control.git
synced 2026-10-06 06:00:33 +02:00
Merge pull request #3 from saphid/frame-sideload-features
Sideload Linux/Windows builds, install links, and devkit pairing
This commit is contained in:
40 files changed
+5676
-117
No files matched your search
@@ -56,7 +56,10 @@ python3 ui/server.py # anywhere: then open http://127.0.0.1:47810
|
||||
(0.85–1.3×) over ADB (`wm size`, `wm density`, `font_scale`). Reset puts all
|
||||
three back. Whether the settings survive the app relaunching is untested.
|
||||
- **Transfer**: drag and drop files to `~/Downloads`; `.apk` files install as
|
||||
their own Android app. Send typed text, or your computer's clipboard, to the
|
||||
their own Android app. A game's `.zip`, folder or `.exe` becomes a title in
|
||||
the Steam library (Valve's Devkit Game path, with Proton or the Steam Linux
|
||||
Runtime picked from the program's header), listed under **Sideloaded titles**
|
||||
with Launch and Remove; see [sideloading.md](sideloading.md). Send typed text, or your computer's clipboard, to the
|
||||
Frame clipboard.
|
||||
- **Flatpaks**: install and remove them (quick picks: Moonlight, Firefox, VLC,
|
||||
Remmina).
|
||||
@@ -69,7 +72,7 @@ python3 ui/server.py # anywhere: then open http://127.0.0.1:47810
|
||||
|
||||
`app/` is an Electron shell. It starts `ui/server.py` on a free loopback port
|
||||
and shows it in its own window; the server stops when you quit the app. The
|
||||
app bundles `ui/`, `scripts/`, `frame/android/` and the rated catalogue from
|
||||
app bundles `ui/`, `scripts/`, `frame/android/`, Valve's `frame/devkit-utils/` and the rated catalogue from
|
||||
`apk-catalog/`, plus a standalone Python
|
||||
([python-build-standalone](https://github.com/astral-sh/python-build-standalone))
|
||||
and `adb` from Google's platform-tools, so there's nothing else to install. It
|
||||
@@ -95,7 +98,7 @@ library capsules and green Play buttons.
|
||||
both capture modes (headset view while in use, and a blank frame in standby,
|
||||
which the UI labels), clipboard, volume, file push, and input validation.
|
||||
**Not yet exercised from the UI:** Launch, Flatpak install/remove, APK drop,
|
||||
and the power buttons. Each of these calls a command that was verified
|
||||
title sideloading (not yet run on a headset at all), and the power buttons. Each of these calls a command that was verified
|
||||
separately.
|
||||
|
||||
## Per-platform notes
|
||||
|
||||
@@ -48,7 +48,10 @@ Lepton (Android 11, podman container "lepton-dev") ← its own panel, app 305600
|
||||
| **DeoVR (Steam app 837380, Windows/Unity) runs immersively** under Proton ARM64 + FEX: Unity's OpenVR XR plugin finds `OpenVR Headset(Steam Frame)` and the `frame_controller`, the GPU shows as Turnip Adreno 750, and AVPro Video decodes through `MF-MediaEngine-Hardware`. It played 7680×3840 and 8192×4096 H.265 VR180 SBS streams in dome/fisheye mode (`FirstFrameReady`). Unity's own `VideoPlayer` (used for grid thumbnails) fails with `0xc00d36bb`, so thumbnail previews stay blank. The first launch takes about 45 s (`ComputeShaders: InitAsync`). Log: `compatdata/837380/pfx/drive_c/users/steamuser/AppData/LocalLow/Deo VR/Deo VR/Player.log`. **Verified 2026-09-25**, BUILD_ID 20260922.6101926. | [vr-video.md](vr-video.md) |
|
||||
| **Wolvic (VR browser APK) runs in Lepton against SteamVR's OpenXR**, with limits. The stock Lynx build aborts (`Runtime doesn't support selected swapChain color format`: it wants `GL_RGBA8`), and the stock Quest build fails with `XR_ERROR_API_VERSION_UNSUPPORTED`. Patching `DeviceDelegateOpenXR::GetSwapChainCreateInfo` in the Lynx build's `libnative-lib.so` to `GL_SRGB8_ALPHA8` (0x8C43) and re-signing fixes start-up. The Gecko engine then segfaults in `libxul`. The Chromium-engine build (Lynx v1.3-chromium) browses fine as an immersive app. Its page reports `isSessionSupported("immersive-vr") == true`, and `requestSession` succeeds, running about 36 rAF/s, but the headset shows **black** for WebXR content, or Wolvic's loading spinner that never clears, until the session is ended. Video decodes on the software `OMX.google.h264.decoder`. Tapping the URL bar's selection menu crashes it (no clipboard service). Open URLs with `am start -a VIEW -n com.igalia.wolvic/.VRBrowserActivity -d <url>` over the instance's ADB. DevTools is at `localabstract:content_shell_devtools_remote`. **Verified 2026-09-25**, BUILD_ID 20260922.6101926. | Web VR video, [apks.md](apks.md) |
|
||||
| Tailscale runs without root as a userspace `tailscaled` user service (static arm64 build in `~/.local/share/tailscale`, lingering on). In userspace mode, inbound tailnet connections reach the Frame's **loopback**, so every port, including DevTools on 8080, is reachable from the tailnet. **Verified 2026-09-25.** | [tailscale.md](tailscale.md), `scripts/tailscale-on-frame.sh` |
|
||||
| **T3 Code desktop runs natively.** The stock release `T3-Code-0.0.42-arm64.AppImage` in `~/Applications/T3CodeDesktop/` starts with no extra setup: glibc 2.39, `libfuse.so.2`, GTK 3, NSS and libsecret are on the image. `panel-on-frame.sh --name t3code-desktop -- '~/Applications/T3CodeDesktop/T3-Code.AppImage'` gives it its own panel (`valve.steam.desktopgame.2000281357`, `--ozone-platform=x11`). Its bundled server listens on `127.0.0.1:3773` and shows up in onboarding as the `frame` computer, with `passwordStore: gnome-libsecret`. The image has no agent CLI and no `node`. Agents run through the LAN CLIProxyAPI (`llm-proxy.lan:8317`, which resolves on the Frame). Claude Code 2.1.283 comes from `claude.ai/install.sh`, and Codex 0.157.1 from the `codex-aarch64-unknown-linux-musl` release tarball, both into `~/.local/bin`. `with-cliproxy` and a mode-600 `~/.config/cliproxyapi/secrets.env` are copied from the Mac. The wrappers `claude-cliproxy` and `codex-cliproxy` (a `-c model_provider=cliproxy`, `wire_api="responses"`, `env_key="CLIPROXY_API_KEY"`) are set as `providers.claudeAgent.binaryPath` and `providers.codex.binaryPath` in `~/.t3/userdata/settings.json`, and T3 picked that up without a restart. Through the wrappers, `claude auth status` reports `loggedIn: true` (`oauth_token`), and both CLIs answered a prompt with `kimi-k3`. `gamescopectl screenshot` captured another layer (the Lepton T3 app) rather than this panel. `DISPLAY=:0 xwd -id <win>` piped to `ffmpeg` captures the window itself (1920×1080). **Verified 2026-09-26**, BUILD_ID 20260922.6101926. | Running T3 Code as a host on the Frame |
|
||||
| Power actions need `sudo`, which asks for the Developer Mode password over SSH. | Frame Control's power buttons |
|
||||
| **Boot / recovery menu.** Hold Power ~10 s until the LED goes off, then power on while holding the **AUX button on top of the Power button** (not the volume keys) until a text menu appears. Entries: `Current` (SteamOS-A/B + build), `Previous` (the other A/B slot), `Boot from USB`, `Repair Steam Installation`, `Erase User Data` (factory reset), `ADB mode`, `Battery Ship Mode`. It auto-boots `Current` after a ~15 s countdown. **Volume Up/Down (left side) move, AUX (right side) selects.** For a boot loop, Valve says pick `Previous` (keeps user data); then `Repair Steam Installation`; `Erase User Data` wipes `~` (SSH keys, Tailscale, Flatpaks, T3 setup). Last resort is a full re-image, two ways: (1) USB: write `steamframe-repair-latest.img.bz2` to an 8 GB+ USB-C stick (Balena Etcher on the Mac), pick `Boot from USB`, then use "Wipe Device & Install SteamOS" / "Repair SteamOS" (keeps games and personal content) from the recovery desktop; (2) cable/EDL: `steamframe-repair-qdl-latest.tar.gz`, run `flash.sh` (Linux) or `flash.cmd` (Windows), then with the Frame off for 10 s hold Power + Vol Up + Vol Down for 10 s and plug it in; it reflashes and reboots. Both images: `https://steamdeck-images.steamos.cloud/recovery/` (build 20260922.5153644, 0.3.0, ~4 GB each, no published checksums); local copies in `~/Downloads/steam-frame-recovery/`. Source: Valve's [SteamOS Recovery FAQ](https://help.steampowered.com/en/faqs/view/1B71-EDF2-EB6D-2BB3) and [Installation and Repair FAQ](https://help.steampowered.com/en/faqs/view/65B4-2AA3-5F37-4227), plus a menu photo in [EloiStree/HelloSteamFrame#9](https://github.com/EloiStree/HelloSteamFrame/issues/9). **Inferred** (Valve docs, 2026-09-26); not yet tried on our Frame. | Recovering from a boot loop |
|
||||
| **Boot loop cause: the SteamVR health check.** `steamvr.service` runs `/usr/share/deckard/steamvr-health-check`, which appends `frog:glasses:` to `$XDG_RUNTIME_DIR/steamvr-short-session-tracker` on every failed or <10 s SteamVR run. At 3 it runs `steam-health-check --repair-now`, which **deletes all of `~/.local/share/Steam` (games, login, Developer Mode) and `~/.steam`**, keeping only `registry.vdf`. At 4 it also tries `steamos-bootconf set-mode reboot-other` (fails as the user: `bootenv: Permission denied`). SteamVR normally fails 1–2 times per boot while it waits for the Steam client (`SteamAPI_InitEx failed … Steam is probably not running`, then `fatal stalled cross-thread pipe`). Once Steam has been wiped, it has to re-download a ~210 MB client on every boot, so SteamVR keeps failing, Steam keeps getting wiped and the Frame reboots, in a loop. Also, the Steam updater can deadlock at `Installing update...` (main process blocked writing to the `-child-update-ui` process, which is stuck in `drm_syncobj_array_wait_timeout`). Killing only the `-child-update-ui` process lets the install finish (`package/*.installed` appears). **Fix without sudo:** over USB-C ADB (`adb -s frame shell` works as `steamos` while the Frame is looping; SSH is refused once Developer Mode is lost), truncate both `/run/user/1000/steam{,vr}-short-session-tracker` files and `chmod 444` them (the health check then logs `Permission denied` and does nothing; this is tmpfs, so it resets on reboot). Unstick the updater if needed, let Steam finish installing, then hold Power 10 s and start the Frame normally. `systemctl reboot` over ADB needs interactive auth. After the fix, sign in to Steam and turn Developer Mode back on. **Verified 2026-09-26**, BUILD_ID 20260922.6101926, slot B (clean boot: 0 SteamVR failures, SSH and Tailscale back). | Diagnosing a boot loop |
|
||||
|
||||
## Debug recipes
|
||||
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="referrer" content="no-referrer">
|
||||
<title>Install with Frame Control</title>
|
||||
<!-- Landing page for install links (docs/web-install.md): install.html?manifest=URL
|
||||
or ?url=URL opens frame-control://install?… and offers the download if the
|
||||
app doesn't open. Static, no requests of its own. Not published yet. -->
|
||||
<style>
|
||||
body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: #0d1117; color: #e6edf3;
|
||||
font: 15px/1.5 -apple-system, "Segoe UI", sans-serif; }
|
||||
main { max-width: 520px; padding: 32px; }
|
||||
h1 { font-size: 20px; margin: 0 0 8px; }
|
||||
p { color: #8b98a8; }
|
||||
code { color: #e6edf3; overflow-wrap: anywhere; }
|
||||
a.btn { display: inline-block; margin: 8px 12px 0 0; padding: 9px 16px; border-radius: 3px; text-decoration: none;
|
||||
background: #2d333b; color: #e6edf3; }
|
||||
a.btn.go { background: #1a9fff; color: #fff; font-weight: 600; }
|
||||
.err { color: #ff7b72; }
|
||||
[hidden] { display: none !important; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<main>
|
||||
<h1>Install with Frame Control</h1>
|
||||
<p id="what"></p>
|
||||
<p id="bad" class="err" hidden>This link doesn't name an https:// manifest or file, so there's nothing to install.</p>
|
||||
<div id="actions" hidden>
|
||||
<a class="btn go" id="open">Open in Frame Control</a>
|
||||
<a class="btn" href="https://github.com/saphid/steam-frame/releases/latest">Get Frame Control</a>
|
||||
</div>
|
||||
<p id="missing" hidden>Nothing happened? Frame Control isn't installed on this computer, or is older than the
|
||||
version that handles install links. Get it, open it once, then use the link again.</p>
|
||||
</main>
|
||||
<script>
|
||||
(() => {
|
||||
const q = new URLSearchParams(location.search);
|
||||
const kind = q.has("manifest") ? "manifest" : q.has("url") ? "url" : null;
|
||||
const target = kind && q.get(kind);
|
||||
let ok = false;
|
||||
try {
|
||||
const u = new URL(target);
|
||||
const local = ["localhost", "127.0.0.1"].includes(u.hostname);
|
||||
ok = !u.username && !u.password && (u.protocol === "https:" || (u.protocol === "http:" && local));
|
||||
} catch {}
|
||||
if (!ok) { document.getElementById("bad").hidden = false; return; }
|
||||
const link = `frame-control://install?${kind}=${encodeURIComponent(target)}`;
|
||||
document.getElementById("what").textContent = `From ${new URL(target).hostname}. Frame Control shows what it will `
|
||||
+ "install and asks you before downloading anything.";
|
||||
document.getElementById("open").href = link;
|
||||
document.getElementById("actions").hidden = false;
|
||||
// If the app opens, this page loses focus or is hidden; if not, say how to get it.
|
||||
let left = false;
|
||||
window.addEventListener("blur", () => { left = true; });
|
||||
document.addEventListener("visibilitychange", () => { if (document.hidden) left = true; });
|
||||
setTimeout(() => { if (!left) document.getElementById("missing").hidden = false; }, 2000);
|
||||
location.href = link;
|
||||
})();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
+4
-2
@@ -36,9 +36,11 @@ ssh frame # passwordless from now on
|
||||
`connect.sh` does four things:
|
||||
|
||||
- finds the headset (`frame.local`, then `frame`, or the IP/host you pass in)
|
||||
- creates a dedicated key (`~/.ssh/id_ed25519_frame`)
|
||||
- creates dedicated keys (`~/.ssh/id_ed25519_frame`, plus `~/.ssh/id_rsa_frame_devkit` for pairing)
|
||||
- adds a `Host frame` block to `~/.ssh/config`
|
||||
- runs `ssh-copy-id`, which asks for the Developer Mode password once
|
||||
- tries SteamOS devkit pairing (approve on the headset, no password; **inferred**,
|
||||
see [SSH](ssh.md#password-free-pairing-steamos-devkit-service)), else runs
|
||||
`ssh-copy-id`, which asks for the Developer Mode password once
|
||||
|
||||
Run `./scripts/connect.sh --harden` later if you want to turn off SSH password
|
||||
logins.
|
||||
|
||||
@@ -0,0 +1,171 @@
|
||||
# Sideloading Linux and Windows games
|
||||
|
||||
A game you have as files (an itch.io download, your own build, a DRM-free
|
||||
release) can go into the Frame's Steam library without a Steam store page.
|
||||
Frame Control uses the same path as Valve's
|
||||
[SteamOS Devkit Client](https://gitlab.steamos.cloud/devkit/steamos-devkit):
|
||||
the title becomes a Steam **Devkit Game**, with a runtime (Proton or a Steam
|
||||
Linux Runtime) chosen from the program itself.
|
||||
|
||||
For Android APKs, see [apks.md](apks.md) instead.
|
||||
|
||||
**Status: nothing here has run on a headset yet.** Every device-side step is
|
||||
**inferred from Valve's steamos-devkit source** (release v0.20260925.1). The
|
||||
local steps (reading the zip, picking the program and runtime, building the
|
||||
request) are covered by `tests/test_frame_titles.py`.
|
||||
|
||||
## Using it
|
||||
|
||||
Drop a game's `.zip`, folder or `.exe` on **Send to Frame**. (Folders need the
|
||||
desktop app, which knows where a dropped folder lives; in a plain browser, zip
|
||||
it.) A dialog shows:
|
||||
|
||||
- **Name**: what Steam shows. Steam uses the title id as the name, so it's
|
||||
limited to letters, digits, `_` and `-`; the dialog shows the result.
|
||||
- **Launches**: the program picked to start the game, with the other
|
||||
candidates in the list.
|
||||
- **Runtime**: picked from the program, see below. Windows programs can switch
|
||||
between Proton Experimental and Proton (stable).
|
||||
|
||||
Install copies it to the Frame and registers it with Steam; progress shows in
|
||||
the bar and the activity log. **Sideloaded titles** lists what's installed,
|
||||
with Launch and Remove. **Copy to ~/Downloads instead** keeps the old
|
||||
behaviour for a zip that isn't a game.
|
||||
|
||||
From a terminal:
|
||||
|
||||
```sh
|
||||
python3 ui/frame_titles.py inspect Game.zip # what would be installed, no headset needed
|
||||
python3 ui/frame_titles.py install Game.zip [--name N] [--exe REL] [--runtime R]
|
||||
python3 ui/frame_titles.py list | launch ID | remove ID
|
||||
```
|
||||
|
||||
## Choosing the runtime
|
||||
|
||||
The program's header decides, not its file name:
|
||||
|
||||
| Program | Runtime (Steam compat tool) | `steam_play` | Confidence |
|
||||
|---|---|---|---|
|
||||
| Windows `.exe`, x86-64 (PE machine `0x8664`) | `proton-experimental` | 1 | Inferred: ARM64 Proton runs x86-64 code through FEX |
|
||||
| Windows `.exe`, 32-bit x86 (`0x14c`) or ARM64 (`0xaa64`) | `proton-experimental` | 1 | Inferred |
|
||||
| Linux ELF, aarch64 (`e_machine` `0xB7`) | `SteamLinuxRuntime_4-arm64` | 0 | Verified: starts, but natively (see below) |
|
||||
| Linux ELF, x86-64 (`0x3E`) | `SteamLinuxRuntime_4` | 0 | Verified not to start: the runtime isn't installed (see below) |
|
||||
| Shell script | the runtime of the Linux binary beside it, else `SteamLinuxRuntime_4-arm64` | 0 | Guess |
|
||||
| Anything else (32-bit Linux, other CPUs, DLLs, data) | refused with a message | | |
|
||||
|
||||
Proton Experimental is the default rather than stable because the Frame's
|
||||
ARM64 Proton and FEX stack is new and Proton fixes reach Experimental first.
|
||||
If a game misbehaves, reinstall it with Proton (stable).
|
||||
|
||||
The aliases and settings are the ones Valve's client sends: `RUNTIME_ALIASES`
|
||||
in `devkit_client/__init__.py`, and `gui2._update_game`, which sets
|
||||
`steam_play=1, steam_play_debug=0, steam_play_debug_version=2019` for Proton
|
||||
and `steam_play=0` otherwise, plus `compat_tool=<alias>`. Valve's client only
|
||||
offers `SteamLinuxRuntime_4-arm64` and Lepton when the device reports itself
|
||||
as Deckard (the Frame).
|
||||
|
||||
## Picking the program
|
||||
|
||||
`ui/frame_titles.py` reads every file's header: ELF executables (PIE ones are
|
||||
told from shared libraries by their `PT_INTERP` segment), PE executables (not
|
||||
DLLs) and scripts with `#!`. A zip with a single top-level folder is treated
|
||||
as that folder. Candidates are ranked by:
|
||||
|
||||
1. Not a helper: names like `UnityCrashHandler64`, `CrashReportClient`,
|
||||
`*setup*`, `unins*`, `vc_redist*`, `dxsetup`, `*prereq*`, and anything under
|
||||
`_CommonRedist`, `Redist`, `DirectX` or `Engine` go last.
|
||||
2. Platform: native ARM64 Linux, then Windows x86-64, then x86-64 Linux, then
|
||||
other Windows builds.
|
||||
3. Name: a program named like the zip or folder (build words such as
|
||||
`-linux-arm64` or `_v1.2` are dropped from the name).
|
||||
4. Depth, then size: Unreal's top-level `Game.exe` beats
|
||||
`Game/Binaries/Win64/Game-Win64-Shipping.exe`.
|
||||
|
||||
A top-level shell script beats a Linux binary one folder down (`run.sh` +
|
||||
`bin/game`); a binary next to a script wins. The list in the dialog lets you
|
||||
pick another.
|
||||
|
||||
## What happens on the Frame (inferred)
|
||||
|
||||
1. **Tools.** `frame/devkit-utils/` (Valve's scripts, vendored unmodified, MIT)
|
||||
is copied to `~/devkit-utils`, where Valve's client puts it, unless the
|
||||
stamp file there already matches. Files are merged, not replaced, so a
|
||||
newer copy from Valve's client keeps its extra files.
|
||||
2. **Folder.** `python3 ~/devkit-utils/steamos-prepare-upload --gameid ID`
|
||||
makes `~/devkit-game/ID` and prints `{user, directory}`.
|
||||
3. **Copy.** The files go there with `rsync -a --delete` on macOS and Linux,
|
||||
or `scp -r` into a fresh folder that then replaces it on Windows. Then
|
||||
`chmod -R 755`, the modes Valve's client gives an upload.
|
||||
4. **Register.** `python3 ~/devkit-utils/steam-client-create-shortcut --parms JSON`
|
||||
with `{gameid, directory, argv: [target], env: {}, settings, clear_settings,
|
||||
force_appid: "", lepton_args: ""}`. It writes `ID-argv.json`,
|
||||
`ID-env.json` and `ID-settings.json` next to the folder, then sends
|
||||
`create-shortcut` to the running Steam client over `~/.steam/steam.pipe`
|
||||
(authenticated by `~/.steam/steam.token`) and waits up to 5 s for Steam's
|
||||
answer file. Its `error`, for example "The Steam client is not running",
|
||||
is shown as the install error. The files stay, so installing again with
|
||||
Steam running finishes the job.
|
||||
5. **Launch** is `steam-devkit-rpc run-game gameid=ID`. **Remove** is
|
||||
`steamos-delete --delete-title ID`, which deletes the folder and has Steam
|
||||
drop shortcuts with no folder. Frame Control then removes the `ID-*.json`
|
||||
files that Valve's script leaves behind.
|
||||
|
||||
Frame Control also writes `~/devkit-game/ID-framecontrol.json` (name, source
|
||||
file, target, runtime, size). **Sideloaded titles** lists every folder in
|
||||
`~/devkit-game`, including titles uploaded with Valve's client.
|
||||
|
||||
`argv` is one string, as in Valve's client (the start command may carry
|
||||
arguments), so a program path with spaces is sent in double quotes. How Steam
|
||||
splits that string is **not checked**.
|
||||
|
||||
## Safety
|
||||
|
||||
- Zips are unpacked on your computer first. Entries with absolute paths, `..`,
|
||||
drive letters or `:` anywhere in the path, or links that point outside the
|
||||
zip (or at a folder they're in) are refused. So are zips over 64 GB
|
||||
unpacked, over 200,000 entries, more than 200× compressed past 1 GB, or
|
||||
bigger than the free space.
|
||||
- No symlink is created while unpacking, so no write can be redirected
|
||||
through one. A link to a file inside the zip (`libfoo.so.1 → libfoo.so.1.2`)
|
||||
becomes a copy of that file, which also works on Windows. Links to folders,
|
||||
loops and dangling links are left out.
|
||||
- A dropped folder that contains symlinks (or Windows junctions) is copied on your computer first,
|
||||
with the same rule, because `scp -r` would follow a link out of the folder
|
||||
and upload whatever it points at.
|
||||
- Installs run one at a time, and Remove is refused while one runs.
|
||||
- The title id is limited to `[A-Za-z0-9_-]`, at most 64 characters. Valve's
|
||||
scripts pass it to a shell (`steamos-delete` runs `rm -r` on it). Valve's
|
||||
reserved sideload names (`steam`, `steamvr`, and their `deckard` forms,
|
||||
which would replace the Steam client itself) get `-game` added.
|
||||
- Nothing needs `sudo`; everything goes to your home folder on the Frame.
|
||||
- In the app, a dropped folder is read from its local path by the app's own
|
||||
server, which only accepts requests from its own page (see
|
||||
[frame-control.md](frame-control.md#how-it-works)).
|
||||
|
||||
## Checked on a headset
|
||||
|
||||
Tested 2026-09-26 on a Frame (BUILD_ID 20260922.6101926) with small static test
|
||||
programs and PuTTY's official 64-bit `putty.exe`, through both the command line
|
||||
and the app (inspect, install job, ▶, Remove, and install links):
|
||||
|
||||
- [x] `create-shortcut` registers a title; it shows in the Steam library and in
|
||||
**Sideloaded titles**, and Steam maps it to the chosen compat tool.
|
||||
- [x] `steam-devkit-rpc run-game` starts it (Steam logs `devkit run-game: started
|
||||
devkit game "<id>"`), and Remove (`steamos-delete`) deletes the files, the
|
||||
shortcut and the Proton prefix.
|
||||
- [x] A quoted path in the start command is fine: Steam runs
|
||||
`proton waitforexitandrun "/home/steamos/devkit-game/<id>/<exe>"`.
|
||||
- [x] An x86-64 Windows `.exe` runs under **Proton 11 (stable)** through FEX
|
||||
(ARM64EC) inside the Steam Linux Runtime 4.0 ARM64 container; PuTTY stayed up.
|
||||
Proton Experimental wasn't installed at the time (it was downloading), so it's
|
||||
untested. A Go-built x86-64 test program crashed in `libarm64ecfex.dll`
|
||||
(a FEX limitation with that program, not the sideloading).
|
||||
- [ ] **An aarch64 build runs natively, not in `SteamLinuxRuntime_4-arm64`**:
|
||||
Steam records the mapping (`CompatToolMapping`, `compat_log.txt`) but launches
|
||||
the devkit title without the runtime's `_v2-entry-point` prefix. Fine for a
|
||||
self-contained build; a build that needs the runtime's libraries may not start.
|
||||
- [ ] **An x86-64 Linux build doesn't start**: Steam logs `Tool 4183110 "Steam
|
||||
Linux Runtime 4.0" is found for appID …, but is not installed`, and the Frame
|
||||
doesn't install that x86-64 runtime for a devkit title (a `steam://install/4183110`
|
||||
request did nothing).
|
||||
- [ ] Whether these titles open as flat panels or need anything VR-specific.
|
||||
+41
-1
@@ -33,7 +33,8 @@ unless your router's DNS registers DHCP client names.
|
||||
|
||||
- **Verified on device (2026-09-25):** `avahi-daemon` is running on the Frame
|
||||
and `frame.local` resolves from the Mac over mDNS.
|
||||
- `scripts/connect.sh` tries `frame.local`, then `frame`. If neither works, it tells you to re-run it with the IP.
|
||||
- `scripts/connect.sh` tries `frame.local`, then `frame`, then an mDNS browse for
|
||||
the devkit service (below). If none works, it tells you to re-run it with the IP.
|
||||
Once you have a working address, the `Host frame` alias means you just type
|
||||
`ssh frame`.
|
||||
- To check discovery yourself: `dns-sd -G v4 frame.local` (Ctrl-C to stop), or
|
||||
@@ -55,10 +56,49 @@ Host frame
|
||||
HostName frame.local
|
||||
User steamos
|
||||
IdentityFile ~/.ssh/id_ed25519_frame
|
||||
IdentityFile ~/.ssh/id_rsa_frame_devkit
|
||||
IdentitiesOnly yes
|
||||
ServerAliveInterval 30
|
||||
```
|
||||
|
||||
The script only asks for the password if the pairing below doesn't work.
|
||||
|
||||
## Password-free pairing (SteamOS devkit service)
|
||||
|
||||
From Valve's source ([steamos-devkit-service](https://gitlab.steamos.cloud/devkit/steamos-devkit-service),
|
||||
[steamos-devkit](https://gitlab.steamos.cloud/devkit/steamos-devkit) client). **Verified on a
|
||||
Frame 2026-09-26** (BUILD_ID 20260922.6101926): the service runs with Developer Mode
|
||||
on, `properties.json` answers with `"login": "steamos"`, the headset advertises
|
||||
`_steamos-devkit._tcp` as `frame`, and `/register` needs pairing mode (below). The
|
||||
approve prompt and key install are not verified yet. SteamOS's devkit service is
|
||||
what Valve's Devkit Client uses to pair. `scripts/connect.sh` and
|
||||
`ui/frame_connect.py` try it first:
|
||||
|
||||
- The headset serves HTTP on port **32000** and advertises mDNS
|
||||
`_steamos-devkit._tcp`. `GET /properties.json` gives the `login` user; the
|
||||
script uses it as `User` (unless you set `FRAME_USER`, or it says `root`),
|
||||
for the password fallback too, and keeps it on re-runs.
|
||||
- **Open Steam Settings → Developer → Pair new host in the headset first.**
|
||||
Otherwise `/register` answers at once with `403` `"please put the Steam client
|
||||
in pairing mode: Settings -> Developer -> Pair new host"` (verified). The
|
||||
scripts say so and keep asking for 2 minutes while you open it.
|
||||
- `POST /register` with `ssh-rsa <key> <comment> 900b919520e4cf601998a71eec318fec`
|
||||
(a fixed token from Valve's client) shows an approve prompt inside the
|
||||
headset naming the comment (`frame-control@<your computer>`). It waits 30 s,
|
||||
then installs the key for the device user and turns `sshd` on. The reply is
|
||||
`200 Registered`, or `403` with `{"error": ...}` (declined, timed out, Steam
|
||||
not running).
|
||||
- It only accepts **RSA** keys, hence the second key,
|
||||
`~/.ssh/id_rsa_frame_devkit` (3072-bit).
|
||||
- A host counts as found if port 22 **or** 32000 answers. With no host given,
|
||||
and `frame.local`/`frame` unreachable, it browses `_steamos-devkit._tcp` with
|
||||
`dns-sd` (macOS) or `avahi-browse` (Linux) for a few seconds if installed.
|
||||
- Port 32000 closed, a timeout, or an error: the script says why and falls back
|
||||
to copying the ed25519 key with the Developer Mode password, as before.
|
||||
|
||||
Anyone on your network can send the request, so only approve a prompt you
|
||||
started. `curl http://<frame-ip>:32000/properties.json` shows whether the service is up.
|
||||
|
||||
`~/.ssh/authorized_keys` lives under `/home`, which SteamOS keeps across OS
|
||||
updates (inferred from Deck; the Frame uses the same A/B image scheme).
|
||||
|
||||
|
||||
@@ -0,0 +1,158 @@
|
||||
# Install links for websites
|
||||
|
||||
A website can put an "Install with Frame Control" button next to its download.
|
||||
Clicking it opens Frame Control, which shows what the link wants to install and
|
||||
asks the user. Only after they click **Install** does it download the file and
|
||||
install it on the Frame.
|
||||
|
||||
What's verified: the link parsing, URL rules, manifest parsing, download,
|
||||
size cap and sha256 check, by `tests/test_webinstall.py` and
|
||||
`tests/test_server.py` (no network: a stub server on 127.0.0.1). Installing on
|
||||
the headset is the same code as dropping a file on Frame Control: `.apk` files go
|
||||
to the APK installer ([apks.md](apks.md)), `.zip` and `.exe` files to the
|
||||
Linux/Windows title installer. A link hasn't been clicked through to a headset
|
||||
install yet.
|
||||
|
||||
## The link
|
||||
|
||||
```
|
||||
frame-control://install?manifest=<URL-encoded manifest URL>
|
||||
frame-control://install?url=<URL-encoded file URL>
|
||||
```
|
||||
|
||||
Use `manifest` when you can: it carries the title's name and a sha256, which
|
||||
Frame Control checks before installing. `url` is for a file on its own; the
|
||||
dialog then names the title after the file.
|
||||
|
||||
The manifest is FrameDrop's format, so one manifest serves both apps. The
|
||||
schema may be `framedrop.install/v1` or `frame-control.install/v1`:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "framedrop.install/v1",
|
||||
"name": "My Game",
|
||||
"files": [
|
||||
{ "url": "https://cdn.example.com/mygame-arm64.apk", "sha256": "optional-but-better" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | |
|
||||
|---|---|
|
||||
| `schema` | Required, one of the two above |
|
||||
| `name` | Shown in the confirm dialog (at most 120 characters). Defaults to the file name. APKs are still named in the Steam library by their own label |
|
||||
| `files` | Exactly one entry for now; more is refused with a message |
|
||||
| `files[0].url` | Required. The file to install |
|
||||
| `files[0].sha256` | Optional, 64 hex digits. The download must match or nothing is installed |
|
||||
| `files[0].size` | Optional (Frame Control extension), bytes. Shown up front; the download must match |
|
||||
| `files[0].exe` | Optional (Frame Control extension), for a `.zip` title: the program inside it to run |
|
||||
|
||||
What gets installed depends on the file name's extension:
|
||||
|
||||
| File | Installed as |
|
||||
|---|---|
|
||||
| `.apk` | An Android app in its own Lepton instance with a Steam shortcut ([apks.md](apks.md)) |
|
||||
| `.zip`, `.exe` | A Linux or Windows title. Versions of Frame Control without the title installer say "Linux/Windows titles need a newer Frame Control" |
|
||||
| anything else | Refused |
|
||||
|
||||
## Rules
|
||||
|
||||
Frame Control refuses a link, and downloads nothing, unless:
|
||||
|
||||
- Every URL (the manifest's, the file's and each redirect) is `https://`.
|
||||
`http://` works only for `localhost` or `127.0.0.1`, for testing: only when
|
||||
Frame Control runs with `FRAME_CONTROL_LOCAL_LINKS=1`, and only when the
|
||||
link itself points there. It's off by default so a website's link can't make
|
||||
the app fetch from services on your computer, and a public manifest can
|
||||
never send it there.
|
||||
- No URL has a user name or password in it (`https://user:pw@…`).
|
||||
- No host is, or resolves to, a private, loopback, link-local, CGNAT
|
||||
(100.64.0.0/10), multicast or otherwise non-public address. Every address
|
||||
the name has must be public, it's checked again on every redirect (at most
|
||||
5), and the download connects to the address that was checked.
|
||||
- The file URL ends in a file name with one of the extensions above
|
||||
(`https://example.com/games/` is refused).
|
||||
- The manifest is JSON of at most 256 KB, and the file at most 4 GiB
|
||||
(`MAX_MANIFEST` and `MAX_FILE` in `ui/frame_webinstall.py`).
|
||||
- The user confirms. The dialog shows the title's name, the site the link came
|
||||
from (and the file's host if different), the file name and type, the size if
|
||||
known, and whether a sha256 was given.
|
||||
|
||||
A web page can't install anything itself: it can only open the link. Frame
|
||||
Control's local server refuses requests from web pages, so the only way in is
|
||||
the operating system handing the link to the app, then the user's click.
|
||||
|
||||
## Button for your site
|
||||
|
||||
Paste this where the download is, with your manifest's URL in `MANIFEST`:
|
||||
|
||||
```html
|
||||
<a id="frame-control-install" href="#"
|
||||
style="display:inline-block;padding:10px 18px;border-radius:4px;background:#1a9fff;color:#fff;
|
||||
font:600 15px -apple-system,'Segoe UI',sans-serif;text-decoration:none">Install with Frame Control</a>
|
||||
<script>
|
||||
(() => {
|
||||
const MANIFEST = "https://example.com/mygame/frame-control.json";
|
||||
const GET_APP = "https://github.com/saphid/steam-frame/releases/latest";
|
||||
const button = document.getElementById("frame-control-install");
|
||||
button.href = "frame-control://install?manifest=" + encodeURIComponent(MANIFEST);
|
||||
button.addEventListener("click", () => {
|
||||
// If Frame Control opens, this page loses focus; if it doesn't, offer the download.
|
||||
let left = false;
|
||||
const away = () => { left = true; };
|
||||
window.addEventListener("blur", away, { once: true });
|
||||
setTimeout(() => {
|
||||
window.removeEventListener("blur", away);
|
||||
if (!left && confirm("Frame Control didn't open. Download it?")) location.href = GET_APP;
|
||||
}, 2000);
|
||||
});
|
||||
})();
|
||||
</script>
|
||||
```
|
||||
|
||||
For a single file, use `"frame-control://install?url=" + encodeURIComponent(FILE_URL)`.
|
||||
|
||||
`docs/install.html` is a landing page that does the same from a plain link:
|
||||
`install.html?manifest=<URL-encoded URL>` tries the app and shows a "Get Frame
|
||||
Control" link. It isn't published anywhere yet; host a copy to use it.
|
||||
|
||||
## Testing locally
|
||||
|
||||
Start Frame Control with `FRAME_CONTROL_LOCAL_LINKS=1` in its environment (for
|
||||
example `FRAME_CONTROL_LOCAL_LINKS=1 npm start` in `app/`), then serve the
|
||||
manifest and file from your own computer:
|
||||
|
||||
```sh
|
||||
cd mygame && python3 -m http.server 8000
|
||||
open 'frame-control://install?manifest=http%3A%2F%2Flocalhost%3A8000%2Fmanifest.json' # xdg-open on Linux, start "" on Windows
|
||||
```
|
||||
|
||||
The manifest's file URL must then be `http://localhost:8000/…` or
|
||||
`http://127.0.0.1:8000/…` too.
|
||||
|
||||
## How it works
|
||||
|
||||
- `app/install-link.js` parses the link (only `frame-control://install` with
|
||||
exactly one `manifest` or `url`); `app/main.js` registers the scheme
|
||||
(`app.setAsDefaultProtocolClient`, and electron-builder's `protocols` for the
|
||||
macOS Info.plist and the Linux `.desktop` file). macOS delivers links through
|
||||
`open-url`, Windows and Linux as an argument to a second instance. Links
|
||||
wait in the main process until the page has loaded and asked for them
|
||||
(`frameApp.onInstallLink` in `app/preload.js`). `framedrop://` is left alone.
|
||||
- The page posts the link to `/api/webinstall/check`, which reads the manifest,
|
||||
applies the rules, asks the file's size with a HEAD request and returns a
|
||||
one-time id. Nothing is downloaded.
|
||||
- **Install** posts the id to `/api/webinstall/start`. The server downloads to
|
||||
a temporary folder (progress at `/api/webinstall/job`, cancellable with
|
||||
`/api/webinstall/cancel`), checks size and sha256, hands the file to
|
||||
`frame_webinstall.dispatch()` and deletes the folder.
|
||||
- The app registers the scheme each time it starts, so the last Frame Control
|
||||
started (e.g. a development checkout) handles the links.
|
||||
|
||||
**Quitting during a stalled download.** On macOS and Linux, quitting stops a
|
||||
download at once (`shutdown()` on its socket wakes the blocked read). On
|
||||
Windows that doesn't wake a read in another thread, and closing the handle
|
||||
under a TLS read isn't safe, so a download that has stalled holds the quit for
|
||||
the 4-second grace period until the app stops the server; the partial file is
|
||||
removed on the next start. Downloads that are still moving stop at their next
|
||||
read either way.
|
||||
Reference in new issue
Block a user