Install and update

Perseval ships as a native macOS application. End users do not need Rust, Cargo, Xcode, or a source checkout.

• macOS 13 or newer;
• Apple silicon for the first public beta artifact;
• permission to run a downloaded application;
• a local agent that can export OTLP/HTTP traces, or the built-in demo.

1. Download the latest Perseval macOS archive.
2. Compare its SHA-256 hash with SHA256SUMS on the same GitHub release.
3. Unzip the archive.
4. Move Perseval.app to /Applications.
5. Open Perseval and create a project, or load the local demo from Sources.

The archive contains both the GUI and the bundled read-only MCP executable at:

/Applications/Perseval.app/Contents/Resources/perseval-mcp

For a notarized release, open the app normally. For an ad-hoc signed beta, macOS may block the first launch. Control-click Perseval.app, choose Open, and confirm the application name. Alternatively, use System Settings → Privacy & Security → Open Anyway after the blocked launch.

Do not disable Gatekeeper globally. If the displayed application name, release tag, checksum, or download source differs from the GitHub release, stop and verify the artifact.

Perseval does not yet include an automatic updater.

1. Quit Perseval.
2. Download and verify the new release archive and checksum.
3. Replace /Applications/Perseval.app with the new copy.
4. Reopen it and check Settings → Workspace before sending new traces.

Replacing the app does not delete the persisted workspace. Forward-only storage migrations run when the newer app opens it. Keep a filesystem backup before opening an important workspace with a new beta.

Removing Perseval.app removes the program but intentionally leaves local workspace data and configuration in place. Perseval currently keeps all trace revisions until an explicit cleanup policy exists.

To remove the data too, first open Settings → Workspace and record the effective configuration and workspace paths. Quit Perseval, make any required backup, then remove those directories manually. This operation is irreversible and is not exposed as an in-app button yet.

The GitHub release tag, application version, archive, and checksum must describe the same revision. Release artifacts are produced by GitHub Actions after formatting, Clippy, tests, history secret scanning, dependency advisories, bundle checks, and signature verification pass on the tagged revision.

Homebrew is not supported for the first stable beta. Use the release archive so the application and MCP executable remain one verified bundle.

Continue with First project and first trace.