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.

Installing or Updating

Download the Windows .exe installer or the macOS .pkg installer for the same Kashef Local version supplied by your administrator. Run the installer on the branch master computer; to update, install it over the existing version so your branch data and settings are retained. Current installers are unsigned, so your operating system may ask for local IT approval before installation.

Opening Kashef

Open Kashef Desktop from the Windows tray or the macOS menu bar. The menu starts with a plain status line (Kashef is ready, Kashef is getting ready…, needs attention, or isn't running) followed by whether it is connected to Kashef Cloud and whether any changes are waiting to sync. It offers Open Kashef, Open Command Center, Sync now, and Back up now; Troubleshooting holds Start all services, Restart all services, Open logs, and Open Kashef Cloud. Quit (stops branch services) closes Kashef Desktop and stops the branch services. Everything appears in the active app language, and full-runtime stop is intentionally not a tray action.

Use Open Kashef on the master computer. Home displays the secure local address you can open. With This computer only access, it is the secure address of this computer itself (https://127.0.0.1 followed by the branch's HTTPS port); copy it only for browsers on the master computer. After Branch network access is applied, the Overview shows the shareable branch hostname ending in .local. 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 friendly setup guide instead of Command Center. It walks you through seven short steps, shown on the left (or as dots at the top of a small window): Check this computer, Set up local storage, Connect your branch, Download branch data, Get your team ready, Start Kashef, and Final check. Each step explains what happens, why, and roughly how long it takes. Use Next when the current step is done and Back to review an earlier one. You can close the window at any time; Kashef remembers where you stopped. Use the moon or sun button in the title bar to switch between dark and light mode, and the language button to switch between English and Arabic.

1. Check this computer — Kashef checks disk space, security settings, and the connections it needs. Items marked Must fix stop setup until they are fixed; Tip items are recommendations you can handle later. Press Fix it for me on an item (or Fix everything for me) to let Kashef repair it, then Check again. When everything looks good, press Continue. If Kashef's background service is still starting, the page keeps checking automatically.
2. Set up local storage — Kashef creates the protected local database and starts its helpers. This usually takes 1–3 minutes. If it hits a snag, press Try again; Show details and Copy details help your Kashef contact.
3. Connect your branch — Confirm the Kashef Cloud address and give this computer a name your team will recognize, then press Sign in with Kashef Cloud. Finish signing in and choose the branch in your browser; your password never passes through Kashef Desktop. Every approval is single-use, so start a new sign-in if you need to retry. After connecting, choose who can open Kashef: Only this computer (simplest and most private) or Computers on your branch network. Kashef checks the firewall, certificate, and network before opening access to other computers; if something blocks it, follow the tips shown and keep Only this computer for now. If certificate repair stays unresolved, reinstall the latest Kashef Desktop package over the current installation and check again — do not erase branch data for this.
4. Download branch data — Type SYNC BRANCH and press Start download. You'll see the percentage, what's being copied right now, time so far, and records copied. You can close the window; the download continues. If it stops, press Try again — it continues without signing in again.
5. Get your team ready — Shows who can sign in on this computer, even offline. If nobody can sign in yet, ask your Kashef administrator to give at least one person access to this branch in Kashef Cloud.
6. Start Kashef — Shows each background helper (local database, web app, cloud sync, background tasks, scheduled jobs, analyzer connections, automatic backups) as Running or Starting…. If something stays stuck, press Start services.
7. Final check — Confirms everything works together. When every item is Confirmed, press Finish. If something needs attention, press Fix it for me; Show details, Copy details, and Open logs help support.

A short celebration screen appears when setup finishes; press Start using Kashef to open Command Center. From then on Kashef Desktop opens straight to Command Center and shows any later problem there — it returns to setup only after you log out, disconnect the branch, or choose Start over.

If you need help at any step, use Create support report in the Need a hand? box. The report includes checks that need attention, support codes, and recent operation IDs, but never patient records, passwords, tokens, or private keys. Kashef keeps at most 30 exported support reports on this computer and removes reports older than 30 days after each new export; save a copy elsewhere if support needs it longer.

To restart setup from the very beginning, choose Start over at the top of the guide and type START OVER. Keep the window open while Kashef resets this computer. This erases the branch data stored on this computer and disconnects it from the branch; your data in Kashef Cloud, your backups, and the installed app stay safe. To keep local data, use Disconnect branch in Command Center instead.

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, and every branch service, running. Click the icon to see, at a glance, whether Kashef is ready, whether it is connected to Kashef Cloud, and whether any changes are waiting to sync. From the same menu you can Open Kashef, Open Command Center, Sync now, or Back up now; less common tools such as restarting services and opening logs are under Troubleshooting.

The database, web runtime, queue, scheduler, sync worker, backup worker, and device gateway run only while Kashef Desktop is running. When you choose Quit (stops branch services) from the tray or menu bar, Kashef stops all of them: Local Kashef, synchronization, backups, and analyzer connections become unavailable on this computer and on every branch computer that uses it. If Kashef Desktop closes unexpectedly, the services stop after about one minute. Putting the computer to sleep does not stop them: as long as Kashef Desktop is still open, the services continue when the computer wakes. Opening Kashef Desktop again starts them automatically. A small Kashef Runtime Service (KashefRuntime on Windows and com.kashef.runtime on macOS) stays idle in the background only so Kashef Desktop can start the services without asking for an administrator password.

In Settings, trusted local support can enable Start Kashef Desktop at login. Enable it on the branch master computer so branch services are available after the computer restarts. Each setting becomes unavailable and shows progress while it is being saved, which prevents duplicate clicks.

Home And Background Services

Home is the first place to check when someone says Local Kashef is slow, disconnected, or unavailable. A single status card says whether Kashef is ready, is checking everything, needs your attention, needs a repair, or isn't running, and offers the one action that helps most: Open Kashef when everything works, Download branch data when the branch is not downloaded yet, or Open health check when something is wrong. The Kashef address is shown under the card with a Copy button. The At a glance cards summarize local data, the Kashef web app, cloud sync (including how many changes are waiting), analyzers, backups, and security; click any card to open its page. A pulsing dot next to a page in the sidebar marks something that needs attention there.

The sidebar groups pages by task: Your branch (Cloud sync, Your team, Analyzers, Backups), Keep it healthy (Health check, Background services, Security), and Settings & help (Settings, Branch account, Updates, Logs). A running process alone does not mean Local Kashef is ready: if a required check is blocked, still refreshing, or unsupported, Home does not offer Open Kashef and directs you to Health check instead. Background services also checks whether the local web login responds: a running web process with a failed login appears as needing attention, and shows Checking while that check is pending. Open Health check or the web log for the cause; 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. The Technical details section at the bottom of Background services shows a snapshot of Kashef's internal state for support.

Queue needs a recent signal from its worker, and Scheduler needs both a live worker signal and a recent scheduling tick. After starting either service, allow a short time for those checks. If it still needs attention, open Doctor and that service's log; a running process alone does not prove background work is progressing.

Device gateway shows Not required when this branch has no active device with its local gateway enabled. An inactive or locally disabled device does not need polling. A failed device or incomplete branch setup shows Needs attention instead; open Doctor and the device log, then check the device's connection setup with support.

Kashef restarts a service on its own when it stops unexpectedly or stops responding for about a minute. While this happens, Home, Background services, and Health check show what Kashef is doing (for example Restarting the Kashef web app…) with a progress indicator; no action is needed and it is not reported as a problem. A single slow response is not treated as a failure. After repeated service failures, Kashef stops automatic restart attempts and keeps the failure visible; only then does Home show Kashef needs your attention. Open Health check and the affected service log, correct the cause, then use the offered repair action to retry. Waiting longer does not clear the failure, and a healthy unrelated service does not need restarting.

Sync and Backup are scheduled tasks, so they can be Ready while waiting for their next run without a live worker process. A failed run waiting to retry still needs attention; check its result in Services or Doctor instead of treating the scheduled time as proof of health.

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.

Health Check

Use Health check when Home identifies a degraded or recovery-required condition. It reads the local Runtime Service, database, certificates, integrity, network, disk, and backup state without changing data, and checks again on its own every few seconds while the page is open, so a short blip right after a restart clears by itself. Press Check again to check immediately. When something needs attention, press Fix problems for me: Kashef shows the repairs it proposes and runs nothing until you confirm. If Kashef has nothing it can fix on its own, it says so; open the items listed to see the cause. 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.

Checks needing attention appear first. Expand Passed checks to review checks that succeeded without letting them obscure the problem.

If Health check shows Kashef configuration as needing attention and several services are affected, treat it as one configuration problem. Open the technical details and contact local support to correct the configuration; restarting those services repeatedly will not resolve it. Other independent checks remain visible.

If Local Kashef login fails while the Web process is running, open the Web log and share the diagnosis with local support. A running process alone does not prove the application is usable.

After a repair, Health check runs the diagnosis again. A completed action is shown as repaired only when its check passes. If Repair needs more attention appears, the latest failed check remains visible; open its details or logs, correct the stated cause, and retry instead of repeating unrelated repairs or resetting branch data.

Cloud Sync

Before the first successful download, the Cloud 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 comes from the latest available snapshot, which may be older than the local count; choose Sync Now when you need a new comparison.

No queued changes reported means no pending or failed work was reported in the latest status check. It does not prove that every record was applied on both sides, even when the local and cloud totals match. While the screen says Checking synchronization or Synchronization status unavailable, treat counts and last-sync details as unverified rather than as zero. If it says Synchronization needs attention, review the failed work or conflict count and contact your branch manager or support before retrying a record you do not understand.

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.

An outgoing record stays pending if Kashef Cloud has received it but has not confirmed that it was applied. Do not treat a received record as synchronized yet; check again with Sync Now. A failed or conflicted record stays visible for review instead of being counted as uploaded.

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.

Analyzers

Use the Analyzers 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.

In Local Kashef, the branch status button in the top bar shows Device gateway from the gateway's latest check: Connected when active analyzers were serviced, Not required when no active analyzer is set up for this branch, Needs attention when a configured analyzer could not be serviced, and Pending check until a recent check is available. Not required is normal for branches without analyzers.

Backups And Restore

Use Backups to see the latest attempt and the last successfully verified backup. Run Back up now before updates, service maintenance, or risky local changes. Backups are encrypted and stored in the configured local backup folder. A failed attempt remains visible but is not selected as a restore source. If the latest attempt failed, review the backup log and create a new copy; an older verified copy may still be available. Use Verify backup on the selected file immediately before recovery to confirm it can still be decrypted and its contents match the manifest.

Restore requires choosing a backup file and typing the confirmation phrase. A copy made for another node, branch, or lab company is refused; ask support for an approved cross-computer recovery plan instead of attaching it to this branch. 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 connection area shows the HTTPS address and public CA fingerprint, with buttons to copy the fingerprint and download the certificate for other branch computers; it never shows 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 Your team 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.

Branch Account, Initial Sync, And Logout

Open Branch account 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 setup guide's Download branch data step asks you to type SYNC BRANCH and press Start download. This step prepares a new or explicitly erased local database and downloads the selected branch’s approved data. The live progress area identifies the current operation, phase, percentage, dynamically formatted elapsed time, dataset being downloaded, downloaded pages and records, and durable operation ID. Kashef marks the step Ready only after every required page applies successfully. If sync fails or is canceled, the onboarding window keeps the last percentage, operation ID, and diagnostics instead of returning to the confirmation field. Use Copy details, Open logs, or Create support report, then choose Try again; retry reuses the saved operation and authorization, so you do not need to type SYNC BRANCH or log in again. When a retry cannot apply part of the replacement, Kashef cleans only the incomplete replacement data and keeps the failure details available for support.

When initial sync becomes Ready, opening the local root (/) goes directly to the authorized Branch Panel; without a local session, it sends you to Login first. The Lab Company Panel and branch switcher are not available on a local node, and local installations intentionally do not offer self-registration—accounts must be synchronized from Kashef Cloud. 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.