36 KiB
APK Manager
In APK → Apps → Manage, set Custom Steam name for each app. Leave it blank to restore the original app name. The name survives APK updates and is applied to existing and future Steam entries; if Steam is unavailable, it syncs when Steam is ready. This does not rename the app in Framely or change its package, container or saved data.
Global controller and container lifecycle preferences are under APK → Settings, separate from the application list. Per-application display and launch preferences remain in each app’s management dialog.
APK Manager installs and manages sideloaded Lepton applications on Steam Frame. Use the header switch to move between Plugin Manager and APK Manager in the headset or authenticated network panel. Visiting the device IP opens Plugin Manager by default. APK Manager has its own Apps, Containers and Data cleanup navigation. It is a file-based manager: it has no store, recommendations, download sources, or automatic APK updates.
Requirements and discovery
Install Lepton through Steam first. Framely uses the Steam session user's Lepton and Podman; it does not install Android globally or operate as root. Lepton compatibility varies: Google services, vendor APIs and DRM may be unavailable.
Open APK Manager → Refresh. Discovery reads the standard Lepton context directories, saved Framely records and running containers' compatibility-data labels. It does not start containers during scanning. Steam-managed APKs appear in the container view; use Steam for their updates and removal.
For data stored elsewhere, open Containers → Additional data locations and add the baked directory containing data_overlay/system/packages.xml. Enter the original Lepton context name when it differs from the enclosing directory. Names cannot conflict with containers belonging to other data locations. Paths must belong to the session user. Removing a scan location does not delete its data. Custom tools can use layouts Framely cannot discover; missing locations must be registered explicitly.
Applications are identified by context plus package name. The same package in two containers is treated as two applications. A context name or location change can therefore create a different identity.
Install and update
During APK installation, choose Display mode → Flat window / VR app. The initial selection follows APK detection; updates keep your previous window override. Flat mode displays the Android window, while VR mode hides it and requires the app itself to support VR. A successful installation saves the choice; failed installations preserve the previous setting.
Choose Install APK, select an individual .apk, and review its name, package, version, minimum Android SDK and target container. Inside Frame, the selected APK is inspected directly on the device without a browser upload. A private local snapshot is retained for the confirmation step; the original file is not changed. Uploads from the network panel are staged on Frame's persistent filesystem, not its limited /tmp. Transfer shows actual bytes; subsequent work shows named stages instead of invented percentages.
Inside Frame, file inputs in both management panels use Framely’s built-in file picker, including APKs, plugin packages and language files. It opens Downloads by default, remembers the last selected folder, and provides a lazily loaded folder tree for Home, temporary files and mounted storage, with folder navigation, path entry, search, hidden files and file-type filtering. Select a file and confirm; B/Escape cancels the picker without closing the panel. External browsers continue using their system file picker. The launcher’s Install APK shortcut opens APK Manager.
Framely installs packages into separate Android package directories even when they share a container. Container restarts preserve downloaded resources in Android external storage, including unfinished download fragments and update checkpoints. Unrecognized Lepton media setup hooks are rejected before they can discard those files. Whether a game resumes its download still depends on its own updater. Older single-APK mounts are repaired from the saved APK when available, and legacy OBB resource links are migrated before replacement without deleting their original target. This prevents future loss; resources already deleted by an older startup cannot be reconstructed from the APK alone.
Launcher icons use the highest-density packaged raster resource instead of the first resource-table entry. Existing installations are re-inspected when the panel/launcher refreshes; no APK reinstall is needed. PNG, WebP and JPEG icons retain their original bytes.
Each new app uses its own independent container. Existing shared containers remain discoverable; their existing packages can still be updated or managed, but new package identities cannot be added. Framely does not automatically split, migrate or delete older shared containers or their data. Steam-managed containers remain excluded.
Installation runs in a headless background container without opening the Android desktop, regardless of the selected display mode. After installation, choose Open if desired; installation does not automatically launch the APK. An app with no detected launch entry remains manageable but does not appear in the launcher. Opening an already visible app reuses its running container and virtual gamepad. A headless or fully hidden display, a physical window-size change, or first attaching a new gamepad requires a restart because Lepton cannot safely perform those display or device transitions in place.
To update, open the app's management dialog and choose Install newer APK. Package identity and version are checked; Android enforces signing compatibility during replacement. Downgrades are refused, and signature failures never trigger an uninstall/reinstall workaround. Same-package replacement retains data. Updating may stop the target container, affecting its other applications.
Before replacing an existing installation, Framely saves a container-data snapshot while it is stopped. Scratch overlay work directories, runtime sockets and FIFOs are excluded. Backups include a SHA-256 integrity inventory checked before restoration. Backup failure aborts replacement. Snapshots are recovery material, not a guarantee that every Android data migration is reversible. One-click restore supports sideloaded containers with a single recorded application and a matching data location, including external containers; shared snapshots require manual recovery. Restoration creates another snapshot of the current state and requires launching the app to verify saved data afterward.
Once a modifying operation starts, cancellation is disabled until its actual outcome is known. Uploads and preparation can be cancelled. Switching panels does not stop a submitted task; reopening APK Manager resumes its progress display. Interrupted restores are recovered from a local transaction journal before the next modifying operation. After interruption, use Reconcile installed state before retrying or deleting data. An unreadable container displays Installation state unknown, preserves the previous record and disables launching, reinstallation and deletion until its actual state is reconciled.
Launch and window display
The launcher uses declared MAIN/LAUNCHER, television launcher and recognized VR entries, plus the running Android package manager's resolved launcher entry. Disabled packages/components are excluded. A launch entry does not guarantee that an app will run successfully.
Flat apps use Lepton’s full-display boot path to avoid the Gamescope window-creation failure in per-app mode. A headless container from installation, or a closed display, is restarted when needed; this also stops other apps in the same container. VR apps keep background boot. After ActivityManager reports success, Framely checks that the application and Android display service stay alive before reporting completion. Framely keeps Lepton’s development-context data handling instead of switching an existing container to APK bake mode. A temporary launch adapter uses the installed Lepton libraries without editing Steam’s installation; an unsupported entry script reports an error before starting a cold container. Manually choosing Start container still opens its desktop.
Window handling is automatic by default. Advanced settings → Show Android window is a troubleshooting override, applied on container restart. It does not convert a flat application into VR or a VR application into a flat application. Lepton development contexts may mount their APK at a different path after a restart. Framely re-registers the same signed APK when Android can no longer resolve it, preserving data and reporting failures. Advanced settings also allow selecting an enabled, declared Activity when a nonstandard app needs a different entry.
Launcher favorites, search and manual ordering continue to use stable context/package identities. Updating and refreshing do not reorder icons. Uninstalling hides an icon without deleting its favorite/order record; reinstalling in the same context restores it. Long-press a local Lepton icon to open APK management or removal confirmation.
Close, uninstall and clean data
Close app force-stops only the selected package. Stop container affects every app inside it. All non-Steam sideloaded containers with a verified data location support deletion after confirmation of affected apps and permanent data loss. Standard Lepton context directories are removed as a whole; registered external locations remove only the baked directory, preserving unrelated files in the parent. Uninstalling an app keeps its container unless Delete container is enabled.
Uninstallation retains saved data by default. Enable Delete app data to remove it. If the container contains only this app, this also selects Delete container by default; you can turn it off to keep the container. Shared containers and unknown application states cannot use this option. The backend checks the inventory again before deleting. Container deletion also removes the associated APK cache and Steam library entry, icon and artwork, while keeping historical backups. Retained apps appear under Uninstalled, data retained, where you can reinstall or remove retained data with the same container option.
Android may require the original signed APK to remove an already uninstalled package's retained state. Framely keeps the original APK when it manages an uninstall. If an externally uninstalled app has no recoverable APK, supply its original APK through reinstallation before removing its retained state. Framely does not bypass signing checks or delete arbitrary directories to simulate success.
Data cleanup lists retained data, old APKs, recovery snapshots and expired temporary files. Saved data and backups are not selected by default. Unidentified data is displayed without an automatic deletion action. Each selected item is checked again before removal; a reinstalled application cannot be cleaned as an uninstalled one. Batch results report actual released file bytes and individual failures. File-byte counts may differ from physical disk usage due to compression, reflinks and shared storage.
Logs and recovery without the panel
Use the app's Logs → Export logs to save its operation log. Detailed Android errors remain in logs. Review logs before sharing them.
As the Steam session user, the installed binary also provides these commands:
/var/lib/framely/current/bin/framely apk list
/var/lib/framely/current/bin/framely apk inspect --file /path/to/app.apk
/var/lib/framely/current/bin/framely apk install '{"ticket":"REVIEW_TICKET","approve":true}'
/var/lib/framely/current/bin/framely apk launch '{"app":"CONTEXT/PACKAGE"}'
/var/lib/framely/current/bin/framely apk logs '{"app":"CONTEXT/PACKAGE"}'
/var/lib/framely/current/bin/framely apk cleanup-list
Reviews expire after 15 minutes. APKs, operation records and recovery material are stored in ~/.local/share/framely/apk-manager; managed Lepton data lives under ~/.local/share/lepton/contexts. Framely uninstallation retains these user-owned directories. Back them up before removing Framely; the APK CLI requires a compatible Framely binary, while Lepton remains independently installed through Steam.
Start Framely-managed contexts through the APK panel or the framely apk launch command above. These launch paths preserve downloaded resources and attach persistent storage; a raw Lepton launch does not apply Framely's storage hooks.
Downloaded resources and shader cache
On the next container start after upgrading, Framely moves existing Android shared storage to baked/external inside the context and mounts it directly, outside the Android data overlay. The move preserves partial downloads and checkpoints without copying their contents. If both storage locations already contain data or an unexpected link exists, startup stops and retains both locations for recovery. Already-running containers use the new layout after stopping and launching again. Registered Steam compatibility contexts retain their existing external-storage layout.
Each context also stores Mesa's shader cache in baked/shadercache, mounted at /data/shaders. Cache entries survive container restarts, allowing compatible shaders to be reused; first-time compilation still occurs. Managed context backups include both directories and restore downloaded resources and cache entries together with application data.
Do not invoke Lepton's global cleanup commands as an application-specific uninstall.
Supported formats
The initial implementation supports individual APKs. Optional Quest conversion downloads and verifies a separate framely-q2f-* runtime when selected in the APK install review. It preserves the original APK and reviews the converted, newly signed APK before installation. The runtime and per-package signing keys live in the configured APK storage location and move with it. An existing original APK may reject the new signature; Framely will not silently uninstall it or erase saves. Updating q2f does not automatically reconvert installed games. Games can continue downloading their own OBB data into persistent container storage. Split APK bundles, XAPK/APKM, manual OBB import, Google Play installation and automatic Steam shortcut creation are outside this version. Unsupported bundles are rejected rather than treated as ordinary APKs.
Flat window orientation
In Manage app → Advanced settings → Window orientation, choose Automatic, Landscape, or Portrait. The choice is saved per app and applied at its next launch. Forced portrait uses a tall window rather than rotating content sideways. Changing orientation may restart the shared container and stop other apps in it. VR apps ignore this setting. Flat APK startup also explicitly selects fullscreen and applies it to the created Android task, avoiding a restored freeform desktop window. This affects startup only; later manual resizing remains available.
Moonlight V+ 12.12.12’s connection-creation screen currently crashes on the tested Lepton build because Android’s clipboard service is absent. This is distinct from the window-startup failure. Framely does not modify or re-sign the APK; a compatible Lepton runtime or an app-side fallback is required.
Optional gamepad input
APK → Settings → Gamepad input is off by default, including after upgrading an existing installation. Enable it to forward Steam Input as a standard Android gamepad for APKs opened through Framely. Steam Input is the default source and follows Steam’s controller configurations, including external controllers recognized by Steam. Frame direct retains the original OpenVR bindings for compatibility. Close and restart a container to change its source. It includes ABXY, the D-pad and diagonals, both sticks and stick clicks, shoulder buttons, analog triggers, Select and Start. Applications must support Android gamepad input; this does not map controls to touchscreen gestures or provide Android VR controller tracking; supported games can request gamepad rumble.
Enabling applies on the next application launch. Framely may restart its container to attach the input device, stopping other apps in that container. Disabling stops forwarding immediately. Only one Framely-launched APK receives input at a time. Switching apps, closing an app, transient process-query failures and foreground changes neutralize input without removing the virtual pad. Each running container retains its device for reuse; container stop, disabling the feature or session-service restart releases it. After a service restart, launch the APK again to reconnect. Keep the intended Android window selected in Dock; the bridge does not change Steam's physical-controller bindings.
The bridge runs as the Steam session user and requires access to /dev/uinput, active SteamVR and the supported Lepton startup hooks. It does not modify Steam's installed Lepton files. Only its virtual event node and read-only Android key layout are mounted into the target container, where Android claims it exclusively. If this claim fails, no input is forwarded and the launch reports an error. Disable the option to use the normal launch path. Bridge errors are recorded in ~/.local/share/framely/apk-manager/logs/gamepad.log; key presses are not logged. The native helper and Android adapter ship in both offline and core update packages.
Native Steam launches select the input target before startup acknowledgement. Forwarding begins only after Android claims the virtual device and the target application becomes foreground. Frame direct helpers have separate temporary SteamVR identities. Steam Input helpers do not register OpenVR action sets, because that registration can suppress Steam virtual-gamepad enumeration in SDL. Returning to an already running application reselects its input target.
When this option is enabled, launch APKs through the management panel or launcher. A one-shot CLI launch cannot own the persistent input bridge and reports an error instead. For read-only diagnostics, run framely apk input-status '{"app":"CONTEXT/PACKAGE"}' as the Steam session user. It reports Android process, foreground and lifecycle status without input events or Steam tokens; it does not prove that the application handles gamepad events.
Gamepad rumble can be disabled independently and takes effect immediately. Linux FF_RUMBLE effects are acknowledged and sent back to the current source controller. Input source changes, Android foreground loss, disconnects and bridge shutdown stop feedback; stale effects are not resumed. Rumble intensity is capped at half strength and each request at ten seconds. Games must use Android gamepad vibration; phone vibration and Android VR haptics are not forwarded.
Steam Input loads SDL3 from Steam’s bundled ARM64 runtime and reads Steam’s virtual gamepads, never the physical devices directly. Framely’s output has a distinct device identity and is excluded to prevent a feedback loop. If the Steam runtime is unavailable, launch reports an error; choose Frame direct explicitly instead of silently bypassing Steam’s mappings. With multiple source controllers, the most recently active controller supplies input and receives rumble; they are not merged.
可选手柄输入
APK → 设置 → 手柄输入默认关闭，旧配置升级也保持关闭。开启后默认使用 Steam Input，沿用 Steam 的手柄配置，支持 Frame 手柄及 Steam 已识别的外接手柄。可选择 **Frame 直连（兼容模式）**保留原有 OpenVR 输入。切换来源需关闭容器后重新启动；关闭输入立即生效。
支持 ABXY、十字键及斜向、双摇杆及按压、肩键、模拟扳机、Select 与 Start；应用必须原生支持 Android 游戏手柄，不模拟触摸或 VR 控制器追踪。同时仅一个目标 APK 接收输入，Android 前台状态丢失、查询失败时清零，但保留虚拟设备以便恢复。
手柄震动可独立关闭并立即生效。支持游戏请求的 FF_RUMBLE，回传给当前输入手柄；切换来源、失去 Android 前台状态、断连或退出时停止，不恢复旧效果。强度上限为一半，单次请求最长十秒；不转发手机振动或 Android VR 触觉。多个手柄以最近产生有效输入的手柄为来源，不合并输入。
桥接以 Steam 会话用户运行，使用 Steam 随附的 ARM64 SDL3，仅读取 Steam 虚拟手柄。Framely 输出设备使用独立标识并排除自身，避免反馈循环。仅把专用事件节点及只读按键布局挂载进容器，不修改系统或 Steam 安装文件。Frame 直连使用独立的 SteamVR 身份；Steam Input 不注册 OpenVR 输入动作，避免影响 SDL 的虚拟手柄枚举。SDL3 不可用时明确报错，可手动选择 Frame 直连。日志位于 ~/.local/share/framely/apk-manager/logs/gamepad.log，不记录按键。APK 必须从管理面板或启动台启动，单次 CLI 不能持有持续桥接。
Steam Input passthrough
APK → Settings → Controller input source → Steam Input passthrough mounts one Steam-generated event device directly into Android with the correct Steam key layout. It does not create another virtual gamepad or use SDL/OpenVR to remap input. The existing Steam Input bridge remains the default; Frame direct input remains available.
Passthrough chooses the lowest valid Steam controller slot, excluding Framely's own bridge output. It preserves both sticks, analog triggers, buttons and hats. Steam's native node does not supply digital L2/R2: use the bridge if a game needs these buttons or automatic switching between several controllers. The trigger threshold applies only to bridge modes.
A small Android input guard neutralizes background events and gates game-requested force feedback using the same controller-input and rumble switches. Expiring control leases stop input and feedback if the session helper disappears. Native force feedback goes directly to Steam's device; games must request controller vibration. Bridge-specific strength and duration limits do not apply to passthrough.
Only the selected device is mounted, not the entire host input directory. No SteamOS or Lepton installation files are changed. If the device node or Steam controller ownership changes, input stops; close and restart that container after reconnecting the controller. Framely never silently remounts another device or restarts a running game. Diagnostics are written to ~/.local/share/framely/apk-manager/logs/gamepad.log without recording button events.
Steam Input 直通
在 APK → 设置 → 手柄输入来源 → Steam Input 直通 中选择。仅将 Steam 生成的一只手柄事件设备及正确按键布局挂载进 Android，不创建第二只虚拟手柄，也不通过 SDL/OpenVR 重映射。现有 Steam Input 桥接仍为默认，Frame 直连保持可用。
直通选择编号最小的有效 Steam 手柄槽位，排除 Framely 自己生成的桥接输出。支持双摇杆、线性扳机、按键及十字键。Steam 原节点没有数字 L2/R2；需要这两个按键或多手柄自动切换的游戏可继续使用桥接。扳机阈值仅对桥接模式生效。
Android 输入保护层清零后台输入，并使用现有输入及震动开关控制游戏请求的力反馈。控制租约到期后停止输入和震动，避免会话辅助进程退出后继续响应。直通震动直接交给 Steam 原设备；游戏本身必须发出手柄震动请求。桥接专用的强度及持续时间限制不适用于直通。
只挂载选中的设备，不暴露整个主机输入目录，不修改 SteamOS 或 Lepton 安装文件。设备节点重建或 Steam 手柄归属变化后停止输入；重新连接后需关闭并重启该容器，不会静默切换到其他设备或重启游戏。日志位于 ~/.local/share/framely/apk-manager/logs/gamepad.log，不记录按键事件。
Container lifecycle
The APK page provides two persistent switches. Stop container after app exits defaults off: after a confirmed launch, all target app processes must remain absent for 15 seconds before the container stops. Background apps and services keep it alive. Stop container when closing its window defaults on: a confirmed system window-close signal stops the associated container (normally within a few seconds). Switching windows, minimizing, and opening the launcher do not count as closing.
Monitoring pauses during APK mutations and startup checks. A container restart, uncertain process query, or another active app in a legacy shared container prevents stopping. Steam-managed containers are left to Steam. Shutdown uses normal Podman stop with a 10-second grace period; APKs, saves and downloads are retained. Reopening a stopped container takes a cold Android start; with both switches disabled a healthy running container is reused.
SteamOS window-close limitation
On Frame Gamescope 3.16.28-76-ge383171f, both window and Dock close controls log Closing Wayland windows not supported yet. for direct, non-Steam Lepton windows. The close request does not reach Android, so this switch cannot make these controls work on that path. Use Launch through Steam as described below, or the APK panel's Stop container action. Framely does not infer close intent from focus changes or this unscoped log message.
Native Steam / Lepton launches
Launch through Steam defaults to on. Framely registers launchable sideloaded APKs with Steam's native Lepton compatibility tool. Existing opt-outs remain disabled, and Steam-managed titles are not registered again. Registration does not launch or restart applications. Steam must be awake; unavailable registration is retried in the background.
Steam entries show the APK's application name and icon. Framely generates matching library capsules, headers and hero images from the icon, without downloading artwork. The original launcher icon, order and favorites stay intact; the explicit Steam App ID binding excludes duplicate entries from the launcher Steam category. APK updates refresh generated entry metadata.
Generated artwork includes a 600×900 portrait capsule, 920×430 landscape capsule, 3840×1240 text-free hero, 1280×360 transparent logo and 256×256 icon. Portrait titles are centered; landscape capsules use the icon on the left and the title on the right. The hero reserves space for Steam's separate logo overlay. Long titles are fitted using actual font metrics. Rendering uses Steam's existing CEF Canvas and system fonts; no extra runtime, image service or font download is required.
The shortcut icon is a separate file, not a fifth Steam custom-artwork type. Steam can crop hero backgrounds with cover depending on its window shape; the main motifs stay in the central safe band rather than requiring the whole exported image to be visible. An exact Framely-owned icon accidentally written over a landscape capsule by the first artwork build is automatically repaired; unrelated custom images are not replaced.
The same OKLab clustering and area/edge-distribution scoring processes every icon; application names and package IDs do not select colors. Main ornaments retain the selected color's hue and use 80% RGB intensity. Icons without a reliable chromatic candidate use a neutral palette. Package IDs seed only the stable decoration layout, so refreshing does not randomly change the design.
Framely stores generated image-content hashes in its private Devkit entry directory. Updates replace only missing images, unchanged Framely-generated images or exact old icon-only artwork; manually replaced Steam artwork is preserved. Renaming a shortcut refreshes Framely-generated titles during the next Steam synchronization. Steam must be running and its library UI available; otherwise synchronization is deferred.
The native runtime has a steamlaunch-… process/container name, while the APK keeps its existing data directory and Framely identity. No game-data copy, APK reinstall or system compositor modification is required. A private, per-user Lepton entry adapter retains resource storage, selected activity, window orientation, shader cache and optional controller forwarding. It prevents native Lepton from clearing an existing installation after a timestamp change or early exit. Unknown entry-script formats are refused before starting the application.
Close an already running container before switching its launch path. Framely does not restart a running game to assign Steam ownership. Old shared containers remain discoverable, but only one Steam launch may own their data at a time. Duplicate launches are blocked using an ownership lock that survives the native process launch.
On the tested Frame build, native Lepton ownership lets both the window's lower close button and the Dock close button show Steam's exit confirmation. Confirming exit stops the app and its container. Steam Stop and APK management Stop container remain available. This result was verified with an isolated flat APK; application-specific and VR behavior may differ. Direct, non-Steam Lepton windows still encounter that build's unsupported Wayland close path.
Entry metadata and the launch adapter are configured through Steam's existing local library UI API, reached through its local debugging endpoint on port 8080. Framely neither enables the endpoint nor changes Steam launch settings to enable it. If the API is unavailable or the shortcut target cannot be verified, registration reports an error and retries; it does not edit the live shortcuts database or silently switch to an unprotected launch. This Steam UI interface can change with Steam updates.
Disabling Steam launch removes only Framely's entry; close a native Steam app first. Uninstalling an APK stops its native container before removing its entry. APK data is removed only by the explicitly selected uninstall/data-cleanup operation. The same session service verifies process and container boot identities so an old ownership record cannot stop a newer application.
Steam / Lepton 原生启动
通过 Steam 启动默认开启。Framely 使用 Steam 原生 Lepton 兼容工具注册可启动的侧载 APK，保留主动关闭的选择，跳过 Steam 已管理的应用。注册不会启动应用或重启容器；Steam 需要保持唤醒，不可用时会后台重试。
Steam 入口显示 APK 的应用名称和图标，并根据图标生成对应的库封面、横幅和背景图，不联网下载图片。启动台原有图标、排序和收藏不变，通过明确的 Steam App ID 绑定过滤 Steam 分类中的重复入口。APK 更新会刷新生成的入口信息。
原生运行时的进程和容器名为 steamlaunch-…，APK 仍保留原数据目录及 Framely 身份，无需复制游戏数据、重装 APK 或修改系统合成器。平面 APK 启动后会通过 Android 任务接口切换为全屏，避免恢复成桌面内的自由窗口；不会持续锁定用户之后的窗口调整。用户目录内的独立 Lepton 入口适配保留资源目录、选择的启动入口、窗口方向、着色器缓存和可选手柄转发，并防止原生 Lepton 在时间戳变化或短时间退出后清除已有安装。无法识别的入口脚本格式会在启动应用之前拒绝。
切换启动路径之前，需要先关闭已经运行的容器；Framely 不会为了绑定 Steam 重启游戏。旧共享容器仍可识别，但同时只允许一个 Steam 启动占用其数据。跨进程保留的占用锁阻止重复启动及共享数据的并发启动。
独立平面 APK 的实机验证显示，窗口下方和 Dock 的关闭按钮都能弹出 Steam 退出确认，确认后应用和容器停止。也可使用 Steam 的“停止”或 APK 管理中的“停止容器”。具体应用及 VR 应用行为可能不同；直接启动的非 Steam Lepton 窗口仍受当前系统未实现 Wayland 关闭的限制。
名称、图片和启动适配通过 Steam 已有的本地库界面 API 配置，连接其 8080 端口的本地调试接口。Framely 不开启该接口，也不为此修改 Steam 启动设置。API 不可用或快捷方式目标验证失败时，注册显示错误并重试，不直接修改运行中的快捷方式数据库，也不悄悄切换为无数据保护的启动。此 Steam 界面接口可能随 Steam 更新变化。
关闭原生 Steam 应用后，才能关闭“通过 Steam 启动”；关闭开关只移除 Framely 的入口。卸载 APK 时先停止其原生容器，确认 Android 卸载成功后再移除入口。只有明确选择的卸载或数据清理操作才删除应用数据。用户会话服务继续核对进程及容器启动标识，防止旧占用记录停止新的应用。
Container list headings show installed application names; the data path identifies the container. An APK update stops its container before backing up data. If stopping fails or a native Steam launch still owns it, the installation dialog offers Close container with confirmation. Closing interrupts running apps and retains their saves. The reviewed APK remains available so installation can be retried after closing.
Steam entry retention
APK → Settings → Keep installed APKs in Steam defaults to on. Turning it off removes idle Framely-owned entries and disables automatic registration. Launching an app whose Launch through Steam option is enabled registers its entry on demand; after the native launch process and container finish, the entry and its temporary Devkit copy are removed. Installed APKs, containers, saves and downloaded game data are retained. Running entries are protected. Failed or interrupted starts are cleaned up after a startup grace period, with retries when Steam is unavailable. Turning retention back on resumes automatic registration.
Failed installs and damaged containers
A failed first install rolls back only the container, runtime and installation records created by that attempt, retaining operation logs. A failed update keeps the existing container, application data and any backup already created. If safe cleanup fails, the pending state is retained and both installation and cleanup errors are reported.
For older, incomplete Framely-owned containers without an Android package database, choose Clean damaged container in application details or delete the container from the container page. Explicit confirmation permanently deletes its application data, associated APK cache and Steam entries; historical backups remain. Ownership, storage paths and runtime ownership must pass validation. Unreadable old data is never automatically deleted. After confirming that the data is no longer needed, clean the damaged container and select the APK again. Diagnose the original installation failure using its logs.
Uninstalling while keeping the container
Keeping application data uses Android PackageManager readiness instead of requiring user unlock or external storage mounting. Deleting data still waits for those conditions. Framely boots a stopped container without showing its desktop and repairs only the selected APK registration if needed. It reports startup, PackageManager, unlock, storage and container-exit failures separately. Steam entries are removed after Android confirms successful uninstall; Android success is saved first so a Steam cleanup retry does not uninstall again. Failed startup or uninstall preserves the application record, Steam binding and application data. The error dialog offers Retry and Export logs. A container that cannot boot still requires diagnosis; Framely does not silently delete it or edit Android package databases.
L2/R2 digital button activation is adjustable in APK Manager → Settings, from 1% to 100%, with an 80% default. Both triggers use this threshold with either Steam Input or Frame direct input. Analog trigger travel is unaffected. Saving applies to running bridges immediately; release occurs five percentage points below the selected threshold (at 0% for thresholds below 5%).
Per-app graphics compatibility
Under Manage app → Advanced settings, Framebuffer compatibility fix is off by default. Enable it only for games that play sound but show a black screen (tested with Rock Kingdom on the current Mesa/Zink driver). Restart the app after changing it. The GLES layer validates framebuffer status after texture attachment, only in the selected application; other apps, system drivers, game files and saved data remain unchanged. Turning it off restores the normal rendering path on the next app launch. It is a targeted workaround, not a general graphics or performance enhancement.