Kashef Desktop

What Kashef Desktop Is For

Kashef Desktop is the tray or menu-bar app installed on the branch master computer. Use it to check whether the local Kashef runtime is healthy, whether the branch can reach Kashef Cloud, whether sync has pending work, and whether local services such as the database, web app, queue, scheduler, sync worker, backup worker, and device gateway are running.

Daily staff should still work inside the normal Kashef Branch Panel in the browser. Reception creates orders there, technicians review samples and results there, and finance collects payments there. Kashef Desktop is for local runtime health and support actions.

Opening Kashef

Open Kashef Desktop from the Windows tray or the macOS menu bar. The menu shows the overall app, local-node, cloud, pending-sync, and local-URL status. It provides Open Local Kashef, Open Kashef Cloud, Open Command Center, Start All Services, Restart All Services, Sync Now, Backup Now, View Logs, and Quit Kashef Desktop in the active app language. Full-runtime stop is intentionally not a one-click tray action.

Use Open Local Kashef on the master computer. The Overview displays the secure local address for this branch, normally using the stable kashef-branch.local hostname and HTTPS. Other devices should open only that web address; they must not connect to the database, Runtime Service control plane, or internal service ports.

First-Start Onboarding

After a fresh install, Kashef Desktop opens a full-window onboarding wizard instead of Command Center. Command Center pages and the sidebar stay unavailable until setup succeeds.

The title bar remains visible at the top of the wizard. Drag it to move the window, and use its minimize, maximize/resize, and close controls when needed. The setup content scrolls inside the window, so continue down the page when the wizard is longer than the available screen. Closing the window does not stop the machine-level Runtime Service; reopen Kashef Desktop to continue the saved setup operation.

Review Computer readiness before choosing Continue setup. The checklist shows only items that need attention; checks that are already ready remain represented by the summary at the top. Each visible check has an explicit Notice, Critical issue, or Checking state and explains the action in customer-friendly language. Critical issues disable Continue setup; when a safe repair is available, choose Fix issues automatically, then recheck the computer. Notices allow setup to continue, although support may still recommend resolving them. The wizard then creates protected local secrets, prepares the database, connects the branch, downloads the required branch data, prepares local users and lab services, and verifies the Runtime Service. Keep the window open while the progress indicator moves. If a step fails, read the exact message, correct that issue, then choose Retry step. Use Export support report when local support needs the readiness, Runtime Service, Doctor, health summary, and relevant logs. The report excludes patient records, result data, passwords, tokens, and private keys; Copy support summary provides the short status and support codes. When choosing Branch network later, Kashef checks LAN firewall, certificate, discovery, and port readiness before enabling access. Do not reinstall as a repair shortcut unless support asks you to.

The Runtime Service reconciles the database, web runtime, queue, scheduler, sync worker, device gateway, and backup worker from their actual state; a completed progress item does not claim that a resource is healthy. Near the end, Kashef performs the final health check. When the welcome screen appears, choose Start using Kashef Desktop to enter Command Center.

Resident Mode And Services

Kashef Desktop is designed to stay resident in the tray or menu bar. Closing the window keeps the tray or menu-bar icon available. The machine-level Runtime Service continues to supervise local resources even when the Desktop window is closed or the Desktop process exits.

The database, web runtime, queue, scheduler, sync worker, backup worker, and device gateway are owned by one machine-level Kashef Runtime Service (KashefRuntime on Windows and com.kashef.runtime on macOS). Kashef Desktop is a local control client; it does not own these processes and it does not need to remain open for them to run. Full-runtime stop is an advanced maintenance action and requires an explicit warning confirmation.

In Settings, trusted local support can enable Start Kashef Desktop at login. Each setting becomes unavailable and shows progress while it is being saved, which prevents duplicate clicks. Closing the window keeps the tray or menu-bar icon and local services available.

Overview And Services Screens

The Overview screen is the first place to check when someone says the local node is slow, disconnected, or unavailable. Local Node Health is healthy only when the local login page responds and the initial branch data is ready. Warning triangles in the sidebar identify pages that need attention.

The Overview screen reports the aggregate Runtime Service state and the actual state of each managed resource. The Services screen is for local support actions on an individual resource or a planned restart. Use Restart all only when support has confirmed a restart is needed. Stopping the complete runtime is available only under advanced maintenance and requires confirmation because it makes the local branch unavailable.

If the Kashef Runtime Service is unavailable, the Command Center shows a clear error. Treat this as a local support issue: check whether the master computer is on, whether Kashef is installed correctly, and whether the machine service is running. Do not expose its localhost control endpoint to the branch network.

Doctor

Use Doctor when the Overview identifies a degraded or recovery-required condition. Inspect reads the local Runtime Service, database, certificates, integrity, network, disk, and backup state without changing data. Repair plan shows the proposed safe and destructive actions before anything runs. Safe repairs can restore protected directories, local certificates, or a service registration. Destructive repairs require typing REPAIR and should be used only with local support; copy or verify a backup first.

Sync

Before the first successful download, the Sync screen guides you through initial sync. After the node is ready, that setup status is replaced by the day-to-day sync workspace. It compares local and cloud counts for orders, patients, doctors, users, catalog tests, packages, pricing, invoices, payments, samples, results, and devices. Each row shows whether it is current, needs a download or upload, has queued work, or has failed work. The cloud count is a recent snapshot, so choose Sync Now when you need a new comparison.

Use Automatic synchronization to let this computer check in the background. Choose a frequency from one minute to one hour; turning it off pauses background synchronization but keeps Sync Now available. The screen also shows failed incoming or outgoing records, last sync time, and conflict summaries. Sync Now asks the Runtime Service to keep downloading pages until the node is current, while preserving dependency order. Use it after internet returns, before a planned shutdown, or when a manager asks for an immediate cloud update. Use Retry failed sync only after reading the failed-batch error and fixing the cause.

The local node receives all data shared across its lab company, including patients, doctors, catalog and pricing records. Branch operational records, such as orders, remain limited to the authorized branch. Payment requests, finance references, cashier settings, and user identities download before the records that depend on them, so a completed sync does not leave payments, samples, or results incomplete. Local user activity uploads to Kashef Cloud for one combined audit trail and is not downloaded back into a second local activity feed. A user is synchronized whenever that user can access the authorized branch, even when another branch is set as the user's primary cloud branch. If that cloud account also administers the global platform, Kashef keeps only its branch role and branch permissions on this local node; global administration is never enabled locally.

Profile compositions and the tests inside packages are synchronized after their test and package records. If a profile or package does not add its tests in Local Kashef, choose Sync Now and review Operations & logs if it remains unavailable.

Do not restart the machine while sync is running. Payments, cashier activity, device imports, and pending audit uploads are operational history, so avoid manual cleanup unless the error message tells you exactly what is safe.

Devices

Use the Devices screen for analyzer connectivity, gateway status, and raw message visibility. Device identity, protocol, direction, and mappings are managed from Kashef Cloud and appear as read-only branch data after sync. Trusted local support should only maintain node-specific connection settings such as host, port, serial path, file-drop folder, archive folder, failed folder, and timeout.

Use Test connection after changing a local connection setting. Use the mappings section to review how the analyzer’s test code and optional parameter code connect to Kashef tests and parameters. Unmapped analyzer codes should stay unmatched and go through support review instead of being forced into a patient result.

Backups And Restore

Use Backups to see the latest backup state and run Backup Now before updates, service maintenance, or risky local changes. Backups are encrypted and stored in the configured local backup folder. Use Verify backup to confirm the encrypted file can still be decrypted and its manifest hashes match.

Restore requires choosing a backup file and typing the confirmation phrase. Restore stops sync, device gateway, queue, and scheduler workers, creates a fresh pre-restore backup, restores the database and files, then restarts those services. Only restore when following an approved recovery plan.

Security, Updates, And Logs

The Security screen highlights local risks such as disk encryption, database bind address, Runtime Service bind address, firewall status, the web LAN port, device listener ports, HTTPS certificate status, APP_DEBUG, token state, backup encryption, failed login attempts, and audit hash chain state. The secure local-access area shows the HTTPS address and public CA fingerprint, never a private key. The screen must not display secret values such as tokens, passwords, API keys, or backup encryption keys.

Security reports remain visible when a check is At risk or Blocked; those labels describe the device posture, not a failed refresh. A blocked audit-chain check requires support review, while firewall and disk-encryption warnings identify operating-system settings that must be enabled on the branch computer. Synchronized historical audit entries are validated within their cloud chain segments, and older entries created before hash chaining do not hide the health of new local entries.

The Updates screen shows whether the local version can keep syncing safely. If Update required appears, arrange the update with local support and keep the master computer powered on. Do not retry sync repeatedly in this state.

After an installed update, Kashef Desktop checks and upgrades the local database schema before it starts the web, queue, sync, device, and backup services. This can make the first launch take slightly longer. Keep the app open; if the upgrade cannot finish, dependent services remain stopped and the technical reason is written to Operations & logs instead of allowing workers to run against an older database.

Use Operations & logs as the main support timeline. The default Operations source focuses on failed actions and meaningful maintenance or data operations together with their elapsed time; frequent health and read-only status polling is intentionally omitted. Choose the matching database, sync, backup, device, queue, scheduler, Runtime Service, or web source when deeper error output is needed. User-facing errors deliberately stay short and direct you here; technical details are written to the logs instead of being displayed across the workspace. Secrets and activation tokens are redacted, and log access is limited to known sources and recent line counts. Clear logs deletes the local operation, application, and service log files after confirmation without deleting branch data; use it only after copying or exporting anything support still needs.

The Users page lists the branch users synchronized to this computer and whether each user can sign in locally. Devices and backup actions remain disabled until the initial sync is ready. Security checks explain whether an Unknown state is waiting for initial data or requires an operating-system change.

Login, Initial Sync, And Logout

Open Login when connecting this computer to Kashef Cloud. Confirm the cloud URL and a readable node name, then choose Log in with Kashef Cloud. The browser shows the signed-in account and eligible branches; choose the branch assigned to this computer, or use Switch account first. Logging in stores the branch authorization but does not delete the local database.

After cloud authorization, the onboarding wizard asks you to choose Prepare branch data. Before it prepares local records, Kashef requires you to type SYNC BRANCH. This step prepares a new or explicitly erased local database and downloads the selected branch's operational records together with the lab-company-wide patients, doctors, users with branch access, permissions, settings, catalog, pricing, and devices. Kashef will not overwrite a healthy local branch database: choose Disconnect branch to keep it, or use the separate typed-confirmation Erase local branch data action before starting a replacement sync. The live progress area identifies the current operation—such as pausing services, preparing the database, connecting to Kashef Cloud, downloading and applying records, verifying data, and restarting services—and shows the completed database steps, cloud pages, downloaded records, percentage, elapsed time, and a durable operation checkpoint when available. Kashef marks the node Ready only after every required page applies successfully. Save or export anything that must be kept before confirming. If sync fails, Kashef records the failed phase and operation ID, cleans only the incomplete replacement data, and keeps database-dependent workers stopped. Open Operations & logs for the technical failure and duration, then retry initial sync; you do not need to log in again.

When initial sync becomes Ready, local login opens only the authorized Branch Panel. The Lab Company Panel and branch switcher are not available on a local node. Remember me stores only the local browser session token on this computer and never edits the synchronized cloud account. Manual activation tokens are never entered into Kashef Desktop.

After login, the Login page shows the cloud account that authorized this computer—its name, email, and avatar—together with the authorized lab company's logo and branch identity. Kashef keeps this identity with the node and refreshes it during sync, so an upgraded installation does not lose the authorizing account display. The page also shows the node name, cloud address, and whether initial sync is still required. Disconnect branch removes this computer's cloud authorization and synchronized local-login access while preserving the local branch database and machine configuration. Use it when the branch should be detached but its local data must remain. Erase local branch data is separate and destructive: it requires typing the exact branch name, removes local branch records and access data, and returns the node to setup. Use either action only after copying anything that must be retained.

Uninstall Behavior

Uninstalling Kashef Desktop removes the desktop app, the machine Runtime Service, and its service registration. Local branch data, database files, protected secrets, certificates, and backups are retained by default so an upgrade or reinstall can recover the node. Use the installer’s explicit data-removal option only when the branch data has been exported and the authorized operator has confirmed the typed erase phrase. After uninstall, verify that the service is gone before moving or deleting the retained data.

What Not To Do

Do not use Kashef Desktop as a replacement for the Branch Panel. Orders, samples, results, payments, device review, and patient work should stay in the browser workflow where permissions, audit logs, and clinical checks are applied.

Do not expose the Runtime Service control plane to the network, open database ports to client computers, or let ordinary staff perform advanced maintenance without a reason. The master computer is the branch appliance; keep it stable, encrypted, and connected to power and the local network.