# Pharos DX

Pharos DX puts your workstation and dev box in one view. The Tauri 2 app has a
quick tray panel and a Workspace dashboard for Themelio, Beto, Metallo, API,
realtime gateway and both frontends.

The dashboard shows where each service runs, runtime/guardian state, dev-box
application health, Docker endpoint, disk space, the source watcher and takeover
lease. Compatibility compares the checkout against the deployed commit and lists
changes that need delivery before takeover. An unavailable comparison blocks
starting a takeover; hand-back remains available for an active session.

The Workspace, tray panel and confirmation dialogs follow the operating system's
light or dark appearance, including changes while the app is open. Progress
animations respect the system's reduced-motion preference.

The app uses the [Pharos Factory favicon](https://pharosfactory.ai/wp-content/themes/paf/assets/images/favicon.svg),
stored unchanged in `src/assets/pharos.svg`. The macOS menu bar uses its silhouette
as a native template icon, which follows the menu bar's appearance. Regenerate
the desktop bundle icons with `pnpm --filter @pharos/dx icons` after updating the
source artwork. The Workspace uses the same shape with a theme-aware foreground.
The PHAROS wordmark uses regular-weight Inter with wider letter spacing and a
separate DX label. The interface also uses bundled Inter, matching the website,
with its SIL Open Font Licence in
`src/assets/fonts/OFL.txt`. The palette follows the website's deep purple
(`#110050`), pale lilac surfaces and yellow actions (`#f3ff00`); dark appearance
uses violet surfaces and light text.

## Install Pharos DX

Install the [workstation tools and root `.env`](../../../docs/development.md)
first. A packaged app uses those tools and your checkout; Rust and Node/pnpm are
needed only when building the app from source.

### Download a preview

1. Sign into GitHub with access to this private repository and open
   [Pharos DX releases](https://github.com/pharos-ai-factory/pharos-platform/releases).
2. Choose the newest `dx-v…-preview.…` release. Under **Assets**, download the
   installer for your OS from the table below.
3. Follow the installation steps for your OS, then [connect your checkout](#connect-a-workspace).

| OS | Release asset ending | Architecture |
|---|---|---|
| macOS | `_macos-universal.dmg` | Apple Silicon and Intel |
| Windows | `_windows-x64-setup.exe` | x64; development tools run in WSL2 |
| Debian/Ubuntu Linux | `_linux-amd64.deb` | x64 |
| Other compatible Linux desktops | `_linux-x86_64.AppImage` | x64 |

Each release includes `SHA256SUMS` to check your download. Release assets remain
available; they have no CI artifact expiry. The first three-platform preview is
[0.1.0-preview.2](https://github.com/pharos-ai-factory/pharos-platform/releases/tag/dx-v0.1.0-preview.2).
Windows and Linux packages pass automated build checks; native interaction and
takeover on those platforms remain to be qualified.

For an unreleased branch build, open
[Pharos DX desktop checks](https://github.com/pharos-ai-factory/pharos-platform/actions/workflows/dx-desktop.yml),
choose a successful run and download its OS artifact ZIP. If the run reused a
successful build, follow the link in its summary. These artifacts expire after
14 days. CI macOS builds target the architecture in their filename; tagged
releases contain a universal DMG.

### macOS

**Preview limitation:** current installers are ad-hoc signed and have neither
Apple Developer ID signing nor Apple notarisation. macOS may block the first
launch with a warning offering only **OK/Done** and **Move to Bin/Trash**.
Opening this preview requires manual approval in **Privacy & Security**.
If that settings pane does not load, **Open Anyway** is unavailable, or your
organisation prevents approval, the app may remain blocked. Use the
[Make commands](../../../docs/development.md#cli-at-a-glance) while the app is
unavailable. This limitation remains until Developer ID signing and notarisation
are configured for our distributed builds.

1. Open the downloaded `.dmg` and drag **Pharos DX** to **Applications**.
2. Eject the disk image and open **Pharos DX** from Applications.
3. If macOS blocks this trusted preview, dismiss the warning with **OK/Done**.
4. Open **System Settings → Privacy & Security**, scroll to **Security**, and
   choose **Open Anyway** beside Pharos DX, where your organisation permits it.
   The approval button appears in System Settings after the failed launch.
5. Authenticate if requested, then confirm **Open**. See
   [Apple's first-launch guidance](https://support.apple.com/en-us/102445).
6. [Connect your checkout](#connect-a-workspace). The menu-bar icon opens quick
   status; **Open Workspace** shows the full dashboard.

### Windows / WSL2

Run the downloaded NSIS `.exe` and follow its installer, then launch **Pharos DX**
from the Start menu. Preview installers are unsigned, so SmartScreen or your
organisation's policy may require approval. Follow your organisation's process
for trusted previews. The desktop app runs on Windows and requires WebView2;
development tools and source live in WSL2. In **Settings**, enter the Linux
checkout path, such as `/home/you/pharos-platform`, and the distribution name
when using a distribution other than your default. Prepare `.env`, uv, SSH and
Docker inside that distribution before connecting.

### Linux

On Ubuntu/Debian, install the downloaded `.deb` with your package manager and
launch **Pharos DX** from the applications menu. For example, from the download
directory, replacing the example filename with the downloaded one:

```sh
sudo apt install ./Pharos-DX_0.1.0-preview.2_linux-amd64.deb
```

Alternatively, mark the `.AppImage` executable in your file manager and open it.
AppImage needs [FUSE support](https://docs.appimage.org/user-guide/troubleshooting/fuse.html).
A desktop without a tray host can use the Workspace window. Both packages are
built on Ubuntu 24.04; older distributions may lack a compatible glibc even with
AppImage. See [Tauri's compatibility guidance](https://v2.tauri.app/distribute/appimage/#limitations).
On Ubuntu, prefer the DEB so the package manager resolves its declared dependencies.

### Update an installed preview

Finish any deployment, setup or reset operation, then choose **Quit Pharos DX** from the tray
menu. Download the new installer and install it over the existing app. On macOS,
drag the new copy into Applications and choose **Replace**. Keep the checkout
updated too: its controller supplies the app's development commands. Updates
are installed manually; there is no automatic updater yet.

## Connect a workspace

Prepare the [workstation tools](../../../docs/development.md) and root `.env`.
Install a preview package, open Pharos DX and enter the absolute path to a trusted
checkout containing `dx/common/scripts/doctor.py`. The app executes that checkout's
controller, so it follows the same versioned rules as its Make commands. On macOS,
`uv` can be in `~/.local/bin`, Homebrew's standard prefix or the inherited PATH.

Opening the app reads status. Select a row in **Your services**, then click a URL
in **Service details**. Web and API show their own catalogue URLs; internal
services have no standalone browser page. The list also includes GitLab, Waldur,
Argo CD, Ceph and AAI. Addresses come from the same catalogue as `make urls`.
Public links prepare a background connection before opening the native browser.
Administration links prepare operator access and require hand-back first.
Run `make devbox-browser-setup`
once to enable short HTTPS addresses and approve certificate trust. Setup and
deployment also prepare SSH access. Repeat a link after a VPN interruption to reconnect.
**Disconnect browser access** closes this checkout's connection after hand-back.
Windows uses the selected WSL2 distribution and its localhost forwarding; the app
checks reachability from Windows before opening the link.

Use **Take over changes** for automatic selection,
or select a service and choose **Run only this service locally**. An explicit
service selection replaces the current selection. Both actions show the intended
operation before it starts. **Hand back all services** restores the deployed
workloads. Capture logs from a service's inspector and find the private file in
Activity. Raw logs can contain sensitive application output; share them carefully.
The **Compatibility** page offers **Deploy this commit**. Commit your intended
changes and hand back any takeover first, then review the dev-box name, SSH alias
and commit before confirming. This runs the same incremental delivery as
`make reconcile`: changed images build, Argo updates the applications, and the app
shows progress until every application is healthy at the reviewed commit.
Compatibility refreshes afterwards. Private logs are available in **Activity**.
Desktop/documentation-only changes can finish with **Already up to date** after
health checks, preserving the actual deployed commit. See the
[deployment guide](../../../docs/development.md#5-finish-work-or-deliver-a-commit).
The **Dev box** page provides reviewed setup and reset.
The **Credentials** page lists service accounts and offers explicit **Copy** and
timed **Reveal** controls. Values are fetched from the selected dev box on demand
and kept out of Activity and logs. See [credential access](../CREDENTIALS.md).

On Windows, the desktop app runs natively and invokes the controller through WSL2.
Enter the Linux checkout path, such as `/home/you/pharos-platform`, and optionally
the distribution name. These WSL settings appear only on Windows.
Keep the checkout, `.env`, `uv`, SSH configuration, Docker
CLI and takeover prerequisites in that distribution. Log paths refer to WSL files.
The Windows package requires WebView2. The controller does not run in PowerShell.

On Linux, the desktop needs the system WebKitGTK and tray dependencies described
in [Tauri's prerequisites](https://v2.tauri.app/start/prerequisites/). A desktop
with no tray host can use the normal Workspace window. Closing the workspace
hides it when a tray is available. Use **Quit Pharos DX** from the tray menu to
exit. Quitting preserves takeover sessions managed by the existing controller;
the in-app Quit command is guarded while its controller action is running.

## Set up or reset a dev box

Open **Dev box**, enter its `dev-NAME`, SSH alias and dedicated storage disk, then
choose **Check dev box**. The app saves those three values in root `.env` and
reviews the committed source, SSH identity, storage binding, available space,
active takeover lease and application scope. Prepare the VM using the
[dev-box prerequisites](../GUIDE.md#prerequisites), including its runner's SSH
access. The same controller backs `make devbox-setup` and `make devbox-reset`.

**Set up dev box** installs the committed platform or repeats an interrupted
installation. On an older dev box, the review also flags the one-time conversion
that discards its previous application data. Later setups preserve the new data.
The **Optional services** section controls peripheral systems such as Zammad.
Adding one uses the normal setup review. Clearing an installed service opens a
separate destructive review and removes only that service's Application,
namespace, storage, edge routes and database before deploying the remaining
selection. Re-enabling it later creates a fresh instance.
See the [developer walkthrough](../../../docs/development.md) for the first setup
and daily workflow. **Reset** first shows the affected namespaces, volume count and
object-bucket count. A separate confirmation requires acknowledgement of permanent
data removal. It removes the reviewed applications and their data, including
shared PostgreSQL, broker messages, persistent sessions, uploaded files and AAI
realm state, then installs the platform again. The VM, Kubernetes, Ceph, host
certificates, build cache, saved private workstation/runner configuration and
local source remain in place. Reset regenerates in-cluster provider credentials;
existing host and saved AAI credentials may be reused.

Reviews expire after ten minutes. Changing the source, destination, disk, cluster
or application identities requires another review. A maintenance record blocks
takeover and unrelated delivery until the final health gate passes. Namespace,
volume and bucket finalisers remain intact; blocked deletion needs investigation.
After an interrupted operation, inspect its private log in **Activity**, correct
the cause and run the checks again. Reset reviews the resources that still exist;
setup resumes the installation without requesting another data reset.

The strand animation uses the original Pharos Factory website artwork, bundled
in `src/assets/journey`. The progress bar advances on real controller stages;
its segments count completed stages and make no estimate of elapsed time. Progress
is also shown in the tray. Completed stages and the final check use success green.
After the source is transferred, local edits can continue while that reviewed
commit installs. The Quit menu and Command-Q on macOS are guarded during an app operation. If the app closes unexpectedly, the controller continues
writing its private log and applies the same final health gate. Reopen the app and
choose **Check dev box** on the matching setup/reset tab to reconnect from the same
checkout. **Deploy this commit** reconnects to a running app deployment. A terminal
can also reconnect with the original setup/reset command, or `make reconcile` for
an app deployment. If the background worker itself stops, inspect the private log
and any surviving runner process before reviewing another operation.

## Build and verify

Install Node/pnpm, Rust 1.96 and the
[Tauri system prerequisites](https://v2.tauri.app/start/prerequisites/), then run
from the repository root:

```sh
pnpm install --frozen-lockfile
make dx
```

`make doctor` prints the same credential-free status without opening the app.
The Rust backend observes the workstation periodically and sends local Tauri
events to both windows. The webview never polls or connects to the dev box itself.

```sh
pnpm --filter @pharos/dx build
pnpm --filter @pharos/dx test
cargo fmt --manifest-path dx/common/desktop/src-tauri/Cargo.toml --check
cargo test --locked --manifest-path dx/common/desktop/src-tauri/Cargo.toml
cargo clippy --locked --manifest-path dx/common/desktop/src-tauri/Cargo.toml --all-targets -- -D warnings
pnpm --filter @pharos/dx tauri build
```

Install Playwright Chromium with `pnpm exec playwright install chromium` before
running the UI tests. These tests inject a fake IPC boundary and cover deliberate
actions, conflict blocking, stale observations, tray navigation, warning wrapping,
reviewed reset confirmation, destination changes and streamed installation progress.
They complement native launch and live dev-box checks. Repository verification
includes Python diagnostics, architecture restrictions and the frontend build.
The desktop workflow additionally compiles, checks and packages all three OSs.

macOS ARM64 has been built and inspected against the live Colima engine and dev
box, including the deployed-commit conflict and private remote log capture. The
Windows/WSL2 and Linux native interaction lanes still need qualification. CI
packaging alone does not qualify Telepresence or service takeover on a platform.

## Preview releases

Pushing a tag such as `dx-v0.1.0-preview.2` triggers
[the release workflow](../../../.github/workflows/dx-release.yml). It requires
that exact version in `package.json`, `src-tauri/Cargo.toml`, `Cargo.lock` and
`src-tauri/tauri.conf.json`. The workflow checks and packages macOS, Windows and
Linux independently, with UI interaction tests on Linux. All three jobs must
succeed before publication. It assembles four installers, verifies their tag and
checksums, then uploads a draft and publishes the complete GitHub **prerelease**.
The assets are a universal Apple Silicon/Intel DMG, Windows x64 NSIS installer,
and Linux x64 DEB and AppImage, with one `SHA256SUMS` file and installation notes.

Stable application/platform tags cannot trigger a DX release. Published release
assets are immutable in this workflow; publish a new preview tag for fixes.
GitHub repository access is required to download from this private repository.

Preview DMGs use ad-hoc signing and have no Apple Developer ID notarisation.
Gatekeeper may prevent opening them under your organisation's policy. Wider
macOS distribution needs an organisation-owned Developer ID certificate and
notarisation credentials in protected release secrets. These credentials are not
yet configured. See [Tauri's signing guide](https://v2.tauri.app/distribute/sign/macos/).

Windows installers are unsigned. Windows/WSL2 and Linux native interaction and
takeover qualification remain open; the release notes retain those limitations.
Installed apps need the selected checkout's development tools. Rust and a frontend
build are required only when building the desktop app from source.

Updates currently mean downloading the next preview. A future updater needs
signed update artifacts, a protected signing key and an authenticated download
path if the repository is private. The app contains no GitHub access token,
autostart configuration or automatic updater.

## Sign-in provider

**Dev box → Sign-in provider** has a **Use external AAI** switch, off by default.
Save the issuer and private credential file path, then deploy to apply the change.
The switch edits the selected checkout's `.env`; credentials stay in the private
file and never enter this settings view. [Provider setup](../local_aai/external.md)
covers first installation, registered callbacks and returning to local Keycloak.

## Trust boundary

This is workstation tooling for a developer with existing SSH access. Its only
commands are status, takeover, hand-back, reviewed setup/reset, bounded log capture,
allowlisted credential retrieval and opening observed local service URLs. The native backend validates
the destination and access class; administration cannot interrupt a takeover. Existing controller leases, engine ownership and
recovery remain authoritative. Snapshot schema 1 contains selected diagnostic
fields; kubeconfigs, credentials and raw command output never enter that snapshot.
The separate credential channel supports native clipboard Copy and a transient,
explicit Reveal of one password in the Workspace window. It writes no log or cache.
Tauri capabilities permit only local event subscriptions, with a restricted CSP.
A private log can only be opened from this app session's recorded activity and
from the selected checkout's `.local/pharos-dx` directory.