Installation, trust, and recovery

Install and maintain p-track safely

Install an official package for your platform, opt in before p-track contacts GitHub automatically, and keep project backups before opening older data with a newer schema.

Install an official package

Download the package for your operating system and CPU from the official GitHub Releases page. Every package carries the same ptrack executable: the CLI, the terminal dashboard, and the Desktop GUI. In file names, <arch> is amd64 or arm64.

macOS

From the app, Install 'ptrack' Shell Command… writes one managed block to ~/.zprofile. It appends the running app's binary directory to the end of the existing PATH, leaves an existing managed block alone, and takes effect in a new terminal session.

Windows

No Windows package asks for administrator rights. The Desktop GUI uses the Microsoft Edge WebView2 runtime, which ships with Windows 11 and current Windows 10.

Linux

Every Linux package is built for x86-64 and AArch64 on a glibc 2.35 baseline, so it runs on current glibc-based desktops; musl-only systems such as Alpine are not supported.

On NixOS, wrap the downloaded AppImage with the expression in build/linux of the repository instead of compiling p-track.

Choose when to check, download, and install

Manual update checks occur only when you select Check for updates. Automatic checks are off by default and persist only after explicit opt-in. They contact the stable releases for the fixed ro-ag/ptrack GitHub repository.

The About & Updates dialog carries both surfaces: it identifies p-track, its version, its build, and its Apache-2.0 license, links to the project, license, Help Center, and issue tracker, and holds the check, download, and install actions. Open it from the version chip, from p-track ▸ Check for Updates… in the macOS app menu (Help ▸ Check for Updates… on Windows and Linux), or from the native About item. The automatic-check opt-in is the same setting in that dialog and in Settings ▸ Updates.

Consent is separated into three steps:

1. A check discovers one newer stable release and the exact package for the running OS and CPU.
2. A separate action downloads that exact candidate.
3. A separate action hands off or applies that same verified version.

A check never silently downloads or installs. Prereleases, drafts, development builds, downgrades, generated source archives, unexpected assets, and ambiguous candidates are rejected.

Understand update verification

Downloads are size-bounded and staged in a private directory under the global p-track home. Every release publishes checksums.txt together with checksums.txt.sig, an Ed25519 signature made by the p-track release key. Before it trusts any digest, p-track verifies that signature against the public key built into the running app, on every platform; a release without a valid signature is refused before its package is downloaded. p-track then requires the expected archive layout, executable, platform machine type, and one exact SHA-256 entry from the signed checksums.txt. It rejects links, extra or duplicate entries, path traversal, and digest mismatches, then reopens and rehashes staged files before use.

• macOS: verifies and opens the complete DMG for installation; it never replaces one executable inside the signed app bundle.
• Windows: a copy installed with the MSI opens the verified next MSI, and Windows Installer upgrades it in place without administrator rights. Any other copy revalidates the ZIP and reveals it in Explorer; close p-track and replace the executable manually. The single-file portable restores the copy it unpacked on its next start, so update it by downloading the next _portable.exe.
• Linux AppImage: downloads and verifies the complete new image, then shows it; close p-track and replace the old image yourself, keeping its filename if a launcher points to it.
• Linux Debian, RPM, and Nix: the package manager owns the installation, so p-track offers the release page and refuses downloads or executable replacement. Install the next package with apt or dnf.
• Linux standalone archive: updates only a safely owned standalone executable, using a target lock, verified rollback link, durable recovery journal, atomic replacement, version probe, and rollback on failure. Every helper command has a time limit. It never uses sudo.

Preserve update recovery state

Interrupted stages are revalidated at startup. An unresolved journal, unsafe target, ambiguous backup, or excessive stage backlog enters recovery-required state and blocks new update work.

When recovery is required, close p-track and inspect $PTRACK_HOME/updates or ~/.ptrack/updates together with the installation. On Linux, preserve each .pending-apply-*.json journal and sibling .ptrack-backup-* executable until the installed target is identified. Deleting either first may remove evidence needed for safe rollback. Reinstalling the same or a newer official package is the conservative fallback; do not copy a staged payload into place or bypass its verification.

Local-first security boundary

p-track has no cloud service account and does not send project planning data to a p-track-hosted service. Project records remain in local files. Desktop may expose private loopback endpoints for local agent-run integration while a project is active; their descriptors and session material are stored in the private per-project runtime directory.

The desktop window's content security policy allows scripts only from the app itself, and a detached terminal window can call only the few terminal commands it needs.

The updater does not accept project-supplied update URLs, store credentials, build from source, elevate privileges, or run unattended installation helpers. Update checks contact GitHub only through the manual or opted-in automatic flow.

Privacy and bounded diagnostics

Structured agent event collection is enabled by default; free-text summaries are disabled. The default policy retains the newest 128 accepted events and expires events older than 14 days. The closed event contract rejects raw prompts, messages, transcripts, tool payloads, command arguments or output, environment data, credentials, and hidden reasoning.

Terminal workspace persistence stores layout and descriptors, not terminal screen contents. The scratchpad keeps only the note you type and the snippets you explicitly copy, and a copy that looks like a credential is not saved. ptrack context and MCP get_context redact likely credentials from what they return. Git remote URLs are shown without embedded user names or tokens.

Know where data lives

Set PTRACK_HOME to move the global store and its backups, runtime state, and update staging. WebView localStorage remains a separate application-browser store; it is not part of global.redb.

All three records use a versioned envelope and are repaired field by field when partly invalid. A record p-track cannot read, or one written by a newer version, is reported and read as defaults rather than overwritten, so downgrading never destroys it. Settings ▸ Data & Diagnostics ▸ Reset Application State clears these records and the saved terminal workspaces. It does not touch plans, tasks, notes, backups, or the known-projects list. See the reset actions.

Back up with the documented limits

ptrack backup

The command byte-copies the live project database to <global-home>/backups/<project>-<timestamp>.db and records the path in the global store. There is no built-in restore command.

Safety checklist

1. Install only the package for the intended OS and CPU.
2. Keep automatic update checks off unless GitHub checks are wanted.
3. Let the updater verify the signed checksum manifest; when installing by hand, verify checksums.txt.sig before trusting checksums.txt.
4. Preserve update journals and rollback artifacts during recovery.
5. Back up and stop writers before manual database replacement.