spoopyghosty0--frameport/docs/INSTALL.md

Install and first steps

▶ Watch the install tutorial (about 90 seconds): from the download to the first game on the Steam Frame.

Download the file for your PC from the latest release and unpack it anywhere. No installer or admin rights are needed.

Your PC	Download	Start
Windows 10/11 (x64)	FramePort-windows-x64.zip	FramePort.exe
macOS (Apple Silicon)	FramePort-macos-arm64.zip	FramePort.app
Linux (x64, Ubuntu 22.04 or newer)	FramePort-linux-x64.tar.gz	FramePort/FramePort
Linux (ARM64, Ubuntu 22.04 or newer)	FramePort-linux-arm64.tar.gz	FramePort/FramePort

On first start FramePort downloads the tools it uses (Settings → Tools shows them).

First launch

Starting FramePort again brings its existing window to the front. If a previous instance was left running after its window closed, FramePort recovers it automatically, including on Windows where the GUI lock cannot be read.

FramePort isn't signed with a paid certificate, so the first start shows a warning:

• Windows: "Windows protected your PC" → More info → Run anyway.
• macOS: right-click FramePort.app → Open → Open (once).
• Linux: tar xzf FramePort-linux-x64.tar.gz && ./FramePort/FramePort.

Connecting the Steam Frame

The Frame and your PC must be on the same network (or connected with a USB cable).

1. In FramePort open Steam Frame and click Start setup. Keep that page open.
2. On the Frame, first time only:

   1. Open the SteamVR dashboard → Launch a program → Desktop. The Frame's desktop opens.

   2. Open the app menu (bottom left) → System → Konsole, the Frame's terminal.

   3. Type this setup line and press Enter (on-screen keyboard or any USB or Bluetooth keyboard):

      curl -fsSL https://frameport.app/s | bash
      

      No keyboard? Open the setup page in Chromium on the Frame, tap Copy and paste it into Konsole.

   4. Konsole shows a 4-digit code. When FramePort shows the same code, click Allow. Nothing changes on the Frame before that.

   5. Steam restarts once and the desktop closes. If Steam asks to install Lepton (Valve's Android runtime), confirm it.

FramePort connects within a minute. No password is needed. The setup turns on Developer Mode; What the setup changes lists everything.

Later, FramePort connects to the Frame by itself. If you turn Developer Mode off (Settings → System → Enable Developer Mode), turn it on again there.

Setup command: if your network blocks FramePort's search, click Use the setup command. It shows a line with your PC's address and a one-time code, for example curl -fsS 192.168.1.20:8765/1a2b3c4d | bash. Run it in Konsole instead.

Without Konsole: turn on Developer Mode yourself (Settings → System → Enable Developer Mode), then open Settings → Developer → Pair new host on the Frame. FramePort finds the Frame and asks to connect; approve it in the headset. Install Lepton from FramePort's Steam Frame page afterwards if it's missing.

With a USB cable

A cable works on networks that block the setup, and uploads are faster (about 37 MB/s, three times typical Wi-Fi).

1. On the Frame, turn on Developer Mode (Settings → System → Enable Developer Mode). The cable only works in Developer Mode.
2. Connect the Frame's USB-C port to your PC. No driver is needed.
3. In FramePort click Steam Frame → Set up with a USB cable and follow the steps.

Uploads use the cable whenever it's plugged in. Unplug it any time: FramePort finds the Frame on Wi-Fi again.

Firewalls

If the setup only says "timed out", a firewall on your PC blocks the Frame. After about 45 seconds the setup page says which. Details: Network and firewalls.

Running FramePort on the Frame (experimental)

FramePort can run on the Frame itself, without a PC:

1. Turn on Developer Mode (Settings → System → Enable Developer Mode).
2. In Desktop Mode, download FramePort-linux-arm64.tar.gz, unpack it (tar xzf FramePort-linux-arm64.tar.gz) and start FramePort/FramePort.

With the default Steam library: Now, games appear after you close FramePort and return to Gaming Mode. FramePort also waits while its window is open in Gaming Mode, so you can install several games in one session. Please report anything odd with Report a problem….

Settings → Installing → Steam library controls future installs:

• Now (default): restart Steam after adding shortcuts, waiting while a game, Desktop Mode, or FramePort's local window is open (up to 12 hours). Unchanged shortcuts need no restart.
• Later: save shortcuts without restarting Steam. Keep installing; changes are applied at the next Steam service start, including after a reboot. Restart Steam now applies them immediately. It closes Desktop Mode and FramePort running on the Frame, and asks again if a game is running.
• Off: skip new Steam shortcuts; existing entries stay. FramePort's Play runs the installed launcher directly. Steam and SteamVR must already be running. Steam's per-game overlay, controller setup, and Exit game integration are unavailable; stop the game from FramePort's Monitor. Pending games in Later also use this direct Play path.

CLI: frameport frame steam-library now|later|off saves the setting and applies it to the connected Frame. frameport frame restart-steam applies pending entries now; --yes confirms ending a running game. These settings concern game shortcuts; installing a missing Steam runtime such as Proton can still require a restart.

Installing games

• Install on Frame on a game's page, or select several games in the Library and install them together. Installs run in the background; Activity shows the current one.
• Update all updates every game whose build changed, for example after a FramePort update.
• If the Frame sleeps or leaves the Wi-Fi, installs wait and continue when it's back. While installs run, the Frame stays awake.
• Your own game files are never changed. The patched copy is deleted once the game is on the Frame (Settings → Installing).
• In the downloaded app you can also drag files onto the Library: games, Linux apps, Windows programs or folders.

Game settings… (in the game's menu) shows the settings that matter for that game in plain words: sharpness, refresh rate, controllers, menus, 360° video and mixed reality. Changes are used the next time the game starts.

Rename… (in the game's menu) changes the name in the Library and in Steam; FramePort keeps it from then on. An installed game keeps its Steam entry, artwork and saves (Steam restarts once).

microSD cards and other drives

• The Steam Frame page's Storage section sets where new games go (Install new games to).
• To move an installed game, right-click it → Move to…. The game must be closed; saves and the Steam entry stay.
• A game on a card only starts while the card is inserted.
• Cards formatted as FAT, exFAT or NTFS can't hold games: format the card in SteamOS first.

Why do the controller buttons repeat or do the wrong thing?

SteamVR maps Quest Touch onto the Frame's controller buttons by default: three top buttons repeat Touch Y/B. Choose Game settings → Controllers → Controller buttons to use Mirror or Quest pair for one game, or Settings → Controllers for the library default. Apply to installed games now sends the default to Quest games without an override. Changes take effect at the next launch. See Controller buttons for the diagram, mappings and limits.

Android apps and Windows programs

• Android apps without VR are installed unchanged and shown as a window in the headset. If one shows nothing (or a VR app opens as a window), open Customize on the game's page, set Show as VR or as a flat window and click Update on Frame.
• Add games → Add a Windows program… adds a single Windows program. The Frame runs it as a window through Proton (Valve's tool for running Windows programs).

Install links ("Install with FramePort" buttons)

Some websites have an Install with FramePort button (a https://frameport.app/install?… link):

• Click a button on Windows or Linux: FramePort opens, shows what it would download and asks first. Then it adds the game and installs it on the Frame.
• Add games → Add from a link… takes a button's address (right-click → Copy link) or a direct download link. Use it on macOS, where buttons can't open FramePort yet.
• Settings → Install links turns the buttons on or off.
• Only https:// links to public servers are used. Only install from sites you trust.

Website owners: see Install button.

Typing on the Frame

• Type on Frame (in the sidebar): while this tab is open, your PC's keyboard types on the Frame. Select a text field in the headset and type, or paste longer text into the box.
• Steam's on-screen keyboard works in apps shown as a window. Steam lists that window as Gamescope: leave it open.
• Unity games whose text fields close at once: FramePort suggests the patch Make Unity text fields work. Games added before this patch existed: open the game's menu → Analyze again, then reinstall.

Watching the Frame

• Monitor (in the sidebar) shows the running game's frame rate, CPU, graphics, memory, temperature, power and battery, each with a 2-minute chart. Show details shows more.
• Under Processes, right-click a process to end it. End game closes the game like Steam's Exit game. A lock marks programs Steam or the desktop needs; FramePort asks again before ending those.
• Live view streams what the headset shows, with sound, to your browser. It uses about one CPU core of the Frame, so stop it when you're done.
• Screenshots shows the screenshots you took in the headset, sorted by game and day, to view or download.

Updating

FramePort checks for a new version at start and every 6 hours. When there is one, the Library shows Update now: FramePort downloads it, checks it, restarts and keeps your games and settings. Later skips that version.

• Settings → Updates turns the check off or turns on Install updates automatically.
• Recipes (the tested patches and settings for each game) update by themselves. A game whose recipe changed shows Update on Frame.
• Moved your games? Scan the new folder (or Rescan folders): games found there whose old files are gone keep their library entry, name, artwork, tags and settings, and only their location changes. Settings → Library folders lists the folders FramePort scans; remove the old one there (the games stay). See the FAQ.
• A newer version of a game: right-click it (or use … on its page) → Update with a newer APK… (Quest and Android games) or Update with a newer version… (Linux apps: the new AppImage, archive or folder; PC VR games: the new game folder). Its name, artwork, tags and your settings stay. Then click Update on Frame (or on this PC).
• Dev builds: if you're asked to test a change before its release, use Settings → Updates → Install the latest dev build…. The next release then arrives as a normal update.

PC VR games

PC VR games are Windows VR games. Scan a folder of them (one folder per game) or use Add games → Add a PC game folder…. FramePort asks which program starts the game if it finds more than one.

• Play from this PC (Windows with Steam and SteamVR): Install on this PC adds the game to Steam. Stream it to the Frame with Steam Link.
• Play on the Frame (experimental): on the Steam Frame page, install PC VR games (Proton), then click Install on Frame on the game's page.
• Oculus games (made for Meta's Rift headset) need Revive, which FramePort downloads. Games that check their license through the Oculus app only run on your PC.

Windows games without VR: use Add games → Add a PC game folder… too. The Frame runs them as a window through Proton, like Steam's own Windows games. Whether a game runs depends on Proton.

Linux apps

Add games → Add a Linux app… takes an AppImage (a single-file Linux app) or a .zip/.tar.gz/.tar.xz archive; Add a Linux app folder… takes an unpacked app. Install on Frame uploads it unchanged and adds it to the Steam library.

• Apps built for arm64 (the Frame's processor) run directly. Apps built for x86_64 (most PCs) run through FEX, a translator Steam installs on the Frame the first time; they run slower. The game page shows which kind you have.
• If the app needs libraries the Frame doesn't have, the game page lists them: look for a build that includes them.
• Linux apps also appear in Desktop Mode's app menu. Turn this off on the game page (Desktop Mode).
• SteamVR overlay apps (a wrist watch, a performance display: programs that draw over games instead of being one) are registered with the Frame's SteamVR, which shows them over whatever you play, Quest and PC VR games alike. FramePort recognises them by the .vrmanifest file they ship. By default they start by themselves whenever SteamVR starts (SteamVR overlay → Start with SteamVR on the game page; a small FramePort service on the Frame does this, frameport-vr-overlays); otherwise start the app from your library before the game. Windows overlay apps get the patch SteamVR overlay app (Frame).

Files on the Frame

The Files tab copies files between your PC and the Frame: videos, documents, mods and saves.

• Use Upload files, Upload folder and New folder; right-click an entry to download, rename or delete it. Drag across entries to select several.
• In the downloaded app you can drag files from your PC onto the list.
• Videos, Downloads and Documents are shared by every Quest game (inside the game: /sdcard/Movies, /sdcard/Download, /sdcard/Documents).
• Game storage holds each game's own files. A game's menu → Add videos and files… opens it.

Backing up saves

Steam doesn't sync Quest games' saves. A game's menu (… on its page) → Saves → Back up saves copies them to your PC (close the game first); Back up all saves on the Steam Frame page does every installed Quest game. Restore saves… puts a backup back on the Frame and keeps a copy of the replaced saves there (Undo last restore). Backups live in FramePort's data folder under save-backups/; the 10 newest per game are kept (Settings → Data). Caches and large downloaded content stay out. More in the FAQ.

Share a recipe or report a problem

• Share working recipe… (in the game's menu) opens a GitHub issue with the game's recipe filled in. Accepted recipes become built-in for everyone. Untested games ask how they run after you install or test them.
• Report a problem… (in the game's menu, or Settings → Problems and feedback) saves a diagnostics zip with personal data removed and opens a GitHub issue to attach it to.

Without the app: share a recipe · report a problem.

Uninstalling

Settings → Uninstall FramePort… removes FramePort's data and, if you choose, its games on the Frame (saves can be kept). It first saves your signing keys to Documents: you need them to update your games later. Then delete the FramePort folder.

Verify a download

SHA256SUMS.txt in each release lists the files' checksums: sha256sum -c SHA256SUMS.txt. Each file also has a GitHub build attestation (proof that GitHub built it from this repository): gh attestation verify FramePort-windows-x64.zip -R spoopyghosty0/frameport.

Windows: to show FramePort as the publisher, import FramePort-selfsigned.cer (attached to each release) into Trusted Root Certification Authorities (Current User). The certificate can only sign code; remove it with certmgr.msc. Its SHA-256 fingerprint: 4E:12:98:91:62:C0:E4:50:FB:65:1D:34:BB:73:00:09:7B:78:BE:88:5C:A7:6C:42:23:46:9B:92:A1:59:A7:6E.

For power users: the command line

The command-line version (Python 3.11 or newer) installs from the release's frameport-<version>-py3-none-any.whl with uv tool install <link> (or pipx or pip).

Everything the app does is also a frameport command; frameport --help and frameport <command> --help list every option. The main ones:

Command	What it does
scan <folder> / list / show <game>	add games, list the library, show a game's patches
folders [--add <folder>] [--remove <folder>] / rescan	list the library folders, add or remove one (its games stay); scan them again for new and moved games
add-linux <path> [--exe <program>]	add a Linux app (AppImage, folder or archive)
new-version <game> <path>	point a game at its newer version (APK, Linux app file/folder, PC VR game folder)
recipe <game> --enable/--disable <patch>	change a game's patches (patches lists them all)
build <game> / install <game> / test <game>	build, install on the Frame (--to pc for this PC), launch test
frame discover / frame connect / frame info	find, connect to and describe the Frame
frame send <files> --dest videos / frame storage / frame cleanup	copy files to the Frame, list where they can go, free space
frame drives / frame move <game> --to <drive> / install --dest <drive>	list the Frame's drives, move a game, install to a drive
saves backup <game>|--all / saves list <game> / saves restore <game> [n] / saves undo <game>	back up Quest games' saves to this PC, restore one, undo the last restore
tools status / tools install	the tools FramePort downloads
open-link "<link>"	install from an install button's address or a download link (--yes, --no-install)
diag report <game> / share-recipe <game>	report a problem / share a working recipe
update	update FramePort (--check only checks: exit code 10 = update available)
uninstall-app	uninstall FramePort

Exit codes: 0 done, 1 failed, 2 wrong usage. FRAMEPORT_DEBUG=1 shows full error details; FRAMEPORT_NO_UPDATE_CHECK=1 turns update checks off.