Install, update, and play native game ports.
Project status · Download · Build from source · Documentation · Roadmap
Portcove brings native game ports into one local library. Choose a port, add the game files it needs, and use the desktop app or command-line tool to manage supported installations, updates, and backups. Some ports use an existing installation rather than installing or updating files through Portcove.
Windows development build, October 1, 2026: an installed game, available ports, and real mixed artwork. This is the application, not a mockup; the pictured design and default covers are newer than the published Alpha 2 preview.
Existing Alpha 1 libraries can be carried forward with the documented upgrade and recovery procedure.
Note
Portcove does not include or download ROMs, disc images, BIOS files, or other copyrighted game data. It checks game files locally and does not upload them. You can use their current location, copy them into Portcove, or explicitly move them after reviewing the consequences. A completed Move removes the original only after a verified managed copy is registered.
- Browse a catalog of native ports and manage them as one library. Find ports that can use your game files, then check what each one needs.
- Keep managed versions side by side so updates can be saved for later, installed, checked, or rolled back.
- Install supported downloads, keep older versions, and switch back when needed. Upstream software can handle its own first-launch setup; installation review explains who updates the runtime and where player data lives.
- Get a recommended upstream release, package and download folder for simpler setup routes, or register an existing installation while keeping its files and update workflow under your control.
- Adopt an existing installation by copying it into Portcove without changing the original.
- Check game files locally. A saved location can point to the current file; copying into Portcove leaves the original in place, while Move requires separate authorization. Portcove checks known exact identities and records a local baseline to detect later changes.
- Check downloaded files against the expected checksum before installing them. Catalog-curated acquisition is planned under #315.
- Keep the saved data declared for a port, such as its known save, settings, and mod locations, separately from installed versions; back up and restore that managed data. This does not establish save compatibility across game versions.
- Launch an installed port through the desktop app or the standalone CLI, with the selected library and Portcove's current launch checks.
- Connect another launcher through the public integration routes. Launch-only, library and lifecycle integrations have different capabilities; a named launcher is not a claim that its complete plugin is supported.
- Use the shared Core behavior through Desktop or the independent CLI.
- Discover versioned JSON/JSONL, schemas, capabilities and stable error/exit behavior through the CLI guide and external-author workflow.
Portcove keeps its library, saved game-file locations, and application state local. A GitHub account is optional and is used only to raise the API rate limit; startup and launching do not depend on an account or a Portcove-hosted service.
Warning
Latest technical preview: Alpha 2 — onboarding and storage
Portcove is under active development. It is intended for maintainers and technically comfortable testers using disposable or fully backed-up libraries—not general users or irreplaceable setups.
Portcove 0.1.0-alpha.2 is released as an immutable prerelease. It adds first-play source onboarding, safe Copy and authorized Move intake, shared tool setup, library and per-game storage controls, recoverable relocation, and the documented Alpha 1 upgrade path. Alpha 1 remains available with its frozen release evidence.
A port appearing in the catalog does not mean every platform has completed hands-on testing. Upstream availability, automated checks, and Portcove's own manual testing are tracked separately for each port and platform.
Current priorities and blockers live in the public Portcove Roadmap. The meaning of Alpha, Beta, RC, and V1 lives in docs/ROADMAP.md. The catalog can continue growing without turning every newly discovered port into a V1 blocker.
The first public beta application release targets Windows x86-64 only, at the existing supported Windows/WebView2 baseline. Linux is planned for a subsequent beta; its implementation, support data and completed evidence remain retained. Shared correctness and security checks still apply wherever they run. This changes the application host commitment, not the original platforms of the games in the catalog. The release boundary describes the remaining qualification and publication requirements. No public beta or new platform qualification is claimed here.
For the graphical app, choose a Desktop package for your operating system and processor from the Alpha 2 release. For terminal use, choose the separate CLI archive. The desktop app does not require that archive, and the CLI archive is not a graphical app. GitHub's generated Source code archives are for building Portcove yourself.
| System | Desktop package | Standalone CLI archive |
|---|---|---|
| Windows x64 | Portcove_0.1.0-alpha.2_x64-setup.exe | portcove-windows-x86_64.zip |
| Linux x64, experimental | Portcove_0.1.0-alpha.2_amd64.AppImage, Portcove_0.1.0-alpha.2_amd64.deb, or Portcove-0.1.0-alpha.2-1.x86_64.rpm | portcove-linux-x86_64.tar.gz |
| macOS Intel, experimental | Portcove_0.1.0-alpha.2_x64.dmg | portcove-macos-x86_64.tar.gz |
| macOS Apple silicon, experimental | Portcove_0.1.0-alpha.2_aarch64.dmg | portcove-macos-aarch64.tar.gz |
These are the published Alpha 2 choices; check the selected release page for later versions and their limitations. Application upgrades are manual. Before opening an existing library, follow the upgrade and recovery steps. Read the Alpha 2 release notes for package scope and known limitations.
Windows packages are unsigned; macOS packages are unsigned and not notarized. Keep operating-system security protections enabled. Linux and macOS remain experimental, with hosted build/test evidence and incomplete hands-on package qualification. Verify the download and read the signing/SBOM limits before opening it.
Use a disposable or backed-up library for this technical preview.
The screenshots show the current development build. In the published Alpha 2 app, Review install presents the plan inline, and the launch action is Play now or Complete setup and play. The newer build uses the labels below and a separate installation-review dialog.
- Open Portcove Desktop and choose the local library you intend to use.
- Open Discover, choose a game, and check which original files the port needs and whether it has been tested on your system.
- Choose your own required game files, or enter their local path. Portcove checks them locally when you continue installation. An unsupported or changed input needs attention; do not substitute another edition blindly.
- Choose Review installation. Check the version, download size and install folder, then confirm Install. Wait for verification and preparation to finish.
- When the game is Ready to play, choose Play. Some ports perform their own first-launch preparation or ask a further question. Close the game normally to return to Portcove.
This captured Windows development-build journey shows Ship of Harkinian installing from a verified package, recognizing an exact Ocarina of Time source, preparing its game data, and reaching the title screen. It is separate from Alpha 2 package qualification and does not establish gameplay, audio, save compatibility or physical-controller behavior.
Use the selected port's requirements and current state to choose the next action.
These CLI examples describe the maintained development contract; check your
selected package's --help and capabilities before using a newer command. The
CLI task guide separates current source behavior from published
preview limitations.
| Task | Start here | What the result means |
|---|---|---|
| Inspect a library or port | Open Library/game details, or run portcove status PORT_ID. |
See which version is installed and which actions are available. This leaves your files as they are. |
| Check installed files | Run portcove verify PORT_ID. |
Installed files are compared with their recorded identities. This does not test gameplay or save compatibility. |
| Check original game files | Use Game files in Settings, or portcove source inspect PROFILE_ID and portcove source verify PROFILE_ID. |
Identify the files or check whether they changed. These checks leave the files as they are and do not test a game version. |
| Check for a game update | Run portcove check PORT_ID, or use the game's update check. |
Checking for an update leaves your current version in use. Review the update before installing it. |
| Protect managed saved data | Use the port's backups, or portcove backup create PORT_ID followed by portcove backup list PORT_ID. |
Check which saves and settings are included. Back up your original files separately. Review which files a restore would replace. |
| Correct a moved game file | Use Update file location in Game files, or the reviewed relink route. | The new location must still match the registered content; relinking does not move files or accept changed bytes. |
| Recover an interrupted task | Read Activity and portcove doctor, then follow the operation's reported recovery action. |
Diagnosis does not itself resume or clean up an operation. Retained files or an unknown outcome need the specific supported recovery. |
| Upgrade Portcove itself | Follow application upgrade and recovery. | Published Alpha 2 upgrades are manual. An application update is separate from a game update or catalog refresh. |
Bulk check --all, reconcile --all and update --all continue after a
per-port failure and report each outcome. A completed batch can contain failed
ports; inspect every result. reconcile follows each saved update policy and
can download or activate a release, while check only checks. Saving a policy
does not execute it.
Some steps can’t stop immediately. Wait for the task to finish cancelling and check any recovery instructions. See safe cancellation and interrupted library transfers. Desktop and CLI share library locks and recovery rules; close other clients before a whole-library transfer.
Some declared disc formats or preparation routes need a local chdman or
DolphinTool. Other ports do not. portcove tool list reports each tool's purpose,
resolution and official setup reference; portcove doctor reports missing or
misconfigured prerequisites. Configure a trusted executable only when the
selected route requires it. Portcove does not silently download these executables
or modify the original disc image. See disc-format requirements.
An account is optional. Browsing public releases and ordinary local library use work without signing in; public GitHub requests remain subject to GitHub's request limits. Startup and launching do not require an account.
Use portcove auth set-token to enter a token with hidden input, or the
documented standard-input/environment route for automation. Tokens are not
accepted as positional command arguments. Saved credentials use the operating
system's credential store. See GitHub authentication.
portcove auth login starts the configured GitHub device flow. Follow the
displayed instructions; the CLI follows the required polling interval and
reports denial, expiry or cancellation. portcove auth status shows the active
credential source without exposing the token; portcove auth logout removes a
saved credential, but cannot remove an environment-provided token.
Authentication raises the GitHub API allowance. It does not supply game files, bypass their checks or change a port's support evidence.
Browse the complete descriptive directory in Desktop's Discover or with:
portcove catalog listings
Listings include projects without managed definitions. Visibility does not imply managed installation, compatible originals, gameplay qualification or supported update/backup ownership. Inspect a managed definition's declared requirements and current evidence through the narrower operational commands:
portcove catalog list
portcove catalog show <port-id>
portcove --json catalog export
Contributors author crates/portcove-core/catalog/ports/<stable-id>.json through
the per-ID authoring workflow.
Their descriptive listing and optional strict integration generate
listings.json and
catalog.json; edit the records rather
than these aggregates. Operational definitions record platforms, channels,
required local files, executable layout, user-data paths and qualification facts.
Stable, Preview, and Rolling are game-port release channels—not quality ratings. Preview retains the beta command and serialized value. See docs/CATALOG.md for the full policy.
Discover groups projects only through reviewed game identities. Open a comparison or Why this port? to inspect source editions, platform requirements, evidence and limitations. A recommended starting point appears only when scoped evidence supports it; sparse and single-project cases do not imply “best.” Changing the comparison never changes an installed project, original files, saves or channels.
Search by the original game's title or a project's name. For games with several implementations, Use saves your deliberate project choice in the current library. Discover and Library keep the other implementations available; each retains its own original-file requirements, releases and installation. Viewing an alternative does not change your choice. A single implementation or an entry without a reviewed game identity opens directly.
Library offers the chosen implementation's existing actions, or the sole installed implementation when the choice is unambiguous. If several installed alternatives need a choice, select one deliberately. Filters match an actual implementation; a saved choice outside those filters stays saved. A removed choice asks you to choose again. Missing optional comparison information does not prevent an installed game's supported offline Play path. Choosing a project never transfers saves or replaces another installation.
Explicitly follow independent projects for locally deduplicated release notices
when refreshed; use the Followed filter to find them. There is no mandatory
account, telemetry or background notification service. CLI users can run
portcove --json catalog compare PORT_ID for the same Core result.
- Rust at the version specified in
rust-toolchain.toml - Global Vite+ with environment management
enabled, to select Node from
.node-versionand pnpm frompackage.json. An existing manager providing those exact versions also works; there is no separate Portcove Node installation. - the Tauri 2 platform prerequisites
Development storage defaults are portable: a checkout may use the Windows system drive when its physical paths and free capacity pass preflight. Prefer an SSD for fixture-heavy work. A stricter machine-local policy can impose additional restrictions without changing repository defaults. See docs/DEVELOPMENT-STORAGE.md for the storage checks and private-policy boundary.
From the repository root, set up frontend dependencies and hooks, then run the desktop app. Repeat setup after pulling toolchain changes; it refreshes hooks even when dependencies are already installed.
node scripts/dev-storage.mts preflight
./scripts/bootstrap-quality-tools.ps1 -Profile frontend
node scripts/dev-storage.mts run -- pnpm --dir apps/desktop desktop:devOn Linux/macOS, use ./scripts/bootstrap-quality-tools.sh --profile frontend
for the setup step. vp env install explicitly provisions the checkout's Node
and pnpm when needed; vp env current shows the selected versions. See
development setup for daily and
Core-only profiles.
Build the CLI using the repository storage wrapper:
node scripts/dev-storage.mts run -- cargo build -p portcove-cli --releaseThe documented command requires Node.js to run the storage wrapper and preserve
the repository storage checks and configured paths. The underlying Cargo build
compiles portcove-cli and portcove-core; compilation itself does not require
Node.js, pnpm, Tauri CLI, WebView, or frontend packages, and does not build the
desktop UI. Keep the storage wrapper for repository development.
Running a released CLI does not require Rust, Node.js, pnpm, Tauri CLI, WebView, or frontend packages. It is an operating-system-native program: use the archive matching Windows x64, GNU/Linux x64, Intel macOS, or Apple-silicon macOS. Linux hosts need their normal C runtime and D-Bus/secret-service support when saved credentials are used; macOS and Windows use their system credential facilities.
For repository checks, packaging, and release work, see CONTRIBUTING.md, docs/QUALITY.md, and docs/RELEASING.md.
This example uses Lighthouse, the Banjo-Kazooie native port:
portcove about
portcove doctor
portcove catalog show lighthouse
portcove source add banjo-kazooie "/path/to/Banjo-Kazooie.z64"
portcove plan lighthouse
portcove install lighthouse
portcove exec lighthouse
Use --json for one-result machine output and --jsonl for streaming operations:
portcove --json check --all
portcove --jsonl reconcile lighthouse
Set PORTCOVE_LIBRARY or pass --library <path> to use a specific library root. The CLI is designed for scripts and external frontends; it does not require the desktop app. Current machine behavior is documented in docs/CLI.md, and the capability, ownership, and frontend-support model is documented in docs/INTEGRATIONS.md.
Start with the documentation map. Deeper references cover the architecture, catalog policy, CLI contract, external frontend integration, release stages, and security policy.
Check the live roadmap and existing issues before starting work. Prefer catalog data and shared core adapters; use small title-specific core code when it enables a bounded useful route without duplicating lifecycle authority. See CONTRIBUTING.md for the full workflow.
A signed catalog changes eligible catalog metadata; applying it does not install game updates or update Portcove itself. No publisher key or scheduled fetch is configured by default. Trusting a publisher is a separate explicit decision and permits changes such as release download locations within the implemented format's limits. A signature does not replace release checksum checks, source requirements or platform qualification. Read the format-1 trust, review and recovery contract before configuring this optional route.
Portcove is available under either the MIT License or the Apache License 2.0, at your option.
Portcove is maintained in boburning's public repository and uses AI-assisted development. The project owner is responsible for the changes and release decisions. Published test evidence describes its actual scope; it does not guarantee every port, platform or personal library.
See the contributor workflow, quality checks, architecture and documentation index.