IT deployment guide

Setting up a workspace · IT reference

What does IT need to know to put the desktop app on every computer?

Everything on this page comes from the app’s build configuration and its code. Where something is not settled, the page says so and tells you who to ask.

What the app records, and who can see it, is a different question. That one is answered in What is recorded about you.

The short version

What it is	A small tracker app, one per person per computer. It records; the web app shows the result
Windows	Windows 10 or later, 64-bit. An .exe installer
Install scope	Per user. No admin rights needed
Silent install	Yes: /S
Code signing	The Windows installer bundled with the web app is not code-signed
Network	Outbound HTTPS to one server. Nothing connects in
Updates	In the app, on Windows only. The person presses Install

Operating systems and installers

OS	Needs	Installer	Where things stand
Windows	Windows 10 or later, 64-bit	.exe (NSIS), x64	Available. The only platform the release pipeline publishes
macOS	macOS 12 or later	.dmg	Code signing, notarization and publishing for macOS are still on the backlog
Linux	Debian or Ubuntu, 64-bit	.deb or AppImage	Built, but the Linux code paths have not been through the test pass

Download from Desktop app in the web app’s sidebar (/download). Every signed-in person can open it. An operating system with nothing published shows Coming soon. Each available build shows its version and, when one was recorded, its SHA-256. Check the hash before you put a file into a deployment tool.

The Windows installer is not code-signed

The installer bundled with the web app has no Authenticode signature. On first run, SmartScreen can say “Windows protected your PC”. The download page tells people to choose More info, then Run anyway.

If your computers only run signed software, it will be blocked. The release pipeline signs a build only when a code-signing certificate has been set up for it. Before you deploy a file, open Properties on it: no Digital Signatures tab means it is unsigned.

Installing on Windows

The installer installs for the user who runs it.

Program folder	%LOCALAPPDATA%\WorkflowPulse
Listed in	Settings → Apps, for that user only
Admin rights	Not requested

There is no per-machine installer. Every person who will be tracked needs it in their own profile. A deployment tool has to run it in that user’s context. Run as SYSTEM, it installs into the SYSTEM profile, where no person will ever use it.

Silent install

Yes. The installer is an NSIS installer built by Tauri — CLI 2.11, the version this app is built with — and its template reads these switches:

Switch	What it does
/S	Silent. No windows at all
/P	Passive. A progress bar, and no questions. The in-app updater uses this one
/NS	No Start menu or desktop shortcut
/R	Start the app when a silent or passive install finishes
/D=<folder>	Install into a different folder. It must be the last switch

An unattended install, run as the user:

WorkflowPulse_<version>_x64-setup.exe /S /R

Two things to expect:

• A running copy is closed. If the app is already running for that user, a silent install closes it without asking. Add /R so it comes back.
• WebView2 may be downloaded. The app needs Microsoft’s WebView2 runtime. If a computer does not have it, the installer downloads Microsoft’s bootstrapper from go.microsoft.com and runs it. If that download fails, the install stops. On a network that blocks it, put the WebView2 runtime on the computers first.

Uninstalling

From Settings → Apps, as that user. Uninstalling removes the start-at-sign-in entry. The data folder stays, unless the person ticks the uninstaller’s option to delete the app data.

macOS and Linux, if you have a build

macOS

• Copy the app from the .dmg into Applications.
• At first launch it asks for Screen Recording. Without it, screenshots show only the desktop background and window titles are empty. Grant it, then restart the app.
• Safari, Chrome, Edge, Brave and Arc each ask once for Automation permission. That is how the website domain is read.
• Keyboard and mouse counts need no Accessibility or Input Monitoring permission.

Linux

• The .deb depends on libxdo3 and libxss1.
• Keyboard and mouse counts need the user in the input group: sudo usermod -aG input <user>, then sign out and back in.
• Website domains are not read on Linux.

Where the app keeps its data

One folder per user. Each person on a shared computer has their own.

OS	Folder
Windows	%APPDATA%\com.tech.workflowpulse — the roaming AppData folder
macOS	~/Library/Application Support/com.tech.workflowpulse
Linux	$XDG_DATA_HOME/com.tech.workflowpulse, normally ~/.local/share/com.tech.workflowpulse

Set the environment variable WFP_DATA_DIR to use a different folder.

In the folder	What it holds
workflowpulse.db	The local database: sessions, the upload queue, settings
outbox/screenshots/	Screenshots waiting to upload
logs/	One log file per day. The last 7 are kept
auth.json	The person’s WorkflowPulse sign-in tokens
workflowpulse.toml	Only if you put one there. See the next section

auth.json is a credential

The sign-in tokens are kept in this file, not in Windows Credential Manager or the macOS Keychain. On macOS and Linux the file is readable by that user only. On Windows it has the ordinary permissions of a file in the user’s profile.

Anyone who copies it can act as that person in WorkflowPulse until the sign-in expires or is signed out. Treat it like a password. Keep it out of shared backups and out of support bundles.

The logs follow one rule in the code: ids, counts, statuses and error messages only — never passwords, tokens, window titles or comment text. WFP_LOG_TO_FILE=false stops the log files. WFP_LOG=debug makes them more detailed.

If the server cannot be reached, the app keeps recording into the upload queue and sends it when the connection is back. The desktop app’s Settings shows how many items are waiting, and has a Sync now button.

Pointing the app at the server

Most workspaces do nothing here. A release build already points at the WorkflowPulse service. Change it only if your WorkflowPulse contact gives you a different address.

For each setting, the first of these that is set wins:

1. An environment variable
2. workflowpulse.toml
3. The default built into the app

Setting	workflowpulse.toml	Environment variable	Release-build default
Server API address	base_url under [api]	WFP_API_BASE_URL	https://workflowpulse.techextensor.com/api/v1/
Web app address, for task links	url under [frontend]	WFP_FRONTEND_URL	https://workflowpulse.techextensor.com/
Update channel	channel under [update]	WFP_UPDATE_CHANNEL	stable. Anything other than beta counts as stable
Write log files	to_file under [log]	WFP_LOG_TO_FILE	true
Log level	—	WFP_LOG	info

The app looks for workflowpulse.toml in four places, in this order, and reads the first one it finds:

1. The path in the environment variable WFP_CONFIG
2. The current working folder
3. The folder the app is installed in
4. The data folder above

It reads it once, at start. Restart the app after a change.

[api]
base_url = "https://workflowpulse.techextensor.com/api/v1/"

[frontend]
url = "https://workflowpulse.techextensor.com/"

[update]
channel = "stable"

[log]
to_file = true

A missing / at the end of an address is added for you.

One setting for every user on a computer

The install is per user, so a file in one user’s folders reaches only that user. A system-wide environment variable — WFP_API_BASE_URL, or WFP_CONFIG pointing at a shared file — reaches everyone who signs in to that computer.

Network access

The app only makes outbound connections. Nothing on the network connects to it.

To	Port	When
The server API address above. By default workflowpulse.techextensor.com	443 (HTTPS)	All the time: sign-in, the workspace policy, uploads, the live heartbeat, update checks
Wherever a new version’s installer is hosted	443 (HTTPS)	Only while installing an update. The same server, or a separate file host — ask your WorkflowPulse contact which
go.microsoft.com, then Microsoft’s own WebView2 download	443 (HTTPS)	Only during a Windows install, and only if WebView2 is missing
login.microsoftonline.com	443 (HTTPS)	Only for Microsoft sign-in, from the person’s browser, not from the app
127.0.0.1, a random port	—	Only for Microsoft sign-in, for up to 3 minutes. On the computer itself

How often: a heartbeat every 30 seconds while tracking, the workspace policy about every 15 minutes, and an update check every 6 hours while not tracking.

Proxies and HTTPS inspection

Proxy. The app uses HTTPS_PROXY and NO_PROXY from the environment. Without them, on Windows, it uses the manual proxy set for that user in Internet Options. It does not read a proxy auto-config (PAC) script.

HTTPS inspection. The app’s connection to the server trusts a built-in list of public certificate authorities, not the computer’s certificate store. A proxy that re-signs HTTPS traffic with your company’s own certificate will break it. Exclude the server address from inspection.

Starting at sign-in

The first time someone signs in to the desktop app on a computer, the app switches on start at sign-in for that user. It does this once. After that, the person’s own choice wins: desktop app Settings → Start WorkflowPulse when I sign in to this computer. If they untick it, it stays off.

Started this way, the app opens hidden in the tray.

OS	Where the entry is
Windows	HKCU\Software\Microsoft\Windows\CurrentVersion\Run
macOS	A LaunchAgent in ~/Library/LaunchAgents
Linux	~/.config/autostart

The workspace setting for this does nothing yet

Productivity rules → Tracking and privacy has a box, Always start the desktop app when the computer starts. The desktop app reads it and, as built today, does not act on it. Start at sign-in is decided on each computer, as described above.

When someone quits the app

Closing the window is not always quitting.

Tracking mode	Closing the window	Quitting
Task-start only	Quits the app, after the stop comment if one is due	The same, or Quit in the tray
Always-on background	Only hides it. Tracking carries on in the tray	Quit in the tray

A tenant admin decides whether the app comes back by itself: Productivity rules → Tracking and privacy → Tracker behavior → Reopen the desktop app after someone quits it. The choices are Never, 15 minutes, 30 minutes, 1 hour (the default), 2 hours and 4 hours.

• It applies only when someone quits while signed in. Quitting from the sign-in screen schedules nothing.
• It needs desktop app 0.1.2 or later. The line under the setting says so.
• The app picks up a change when it next reads the workspace policy: at start, and about every 15 minutes.

How the app comes back:

OS	How
Windows	A one-time Task Scheduler task named WorkflowPulse Restart - <username>, run as that user with least privilege. Each quit replaces it. If the computer was off or asleep at that time, it runs at the next sign-in
macOS and Linux	A background timer. It ends when the person signs out; start at sign-in covers the next session

If the app is already running when the time comes, nothing happens. No second copy, no window.

Updates

WorkflowPulse publishes new versions, not you. They go into a release registry that both the web app and the desktop app read.

• /download offers the newest stable build in the registry for each operating system. If the registry has none for an operating system, it offers the build bundled with the web app.
• In the app, on Windows only, it checks every 6 hours while not tracking, and on demand from Settings → Check for updates. When a newer version exists, a banner says Version … is available. with an Install button.

What Install does:

1. Sends everything still waiting in the upload queue.

2. Downloads the new installer and checks its signature against a key built into the app.

3. Runs it in passive mode: a progress bar, no questions, no admin prompt.

4. Restarts the app.

In task-start mode it waits until tracking stops; the button reads Stop tracking to update. In always-on mode it closes the session itself and restarts.

Only a version published with its signature file is offered in the app. One uploaded without it is labelled Manual download only, and people get it from /download. On macOS and Linux there is no in-app update at all: install the new build by hand.

Nothing updates by itself, and nothing forces it

The person has to press Install. The desktop app does not act on the registry’s minimum supported version, so nobody is forced to upgrade.

To move every computer to a new version, either people press Install, or you deploy the new installer the same way you deployed the first one.

To try a version on a few computers before everyone gets it, point them at the beta channel: channel = "beta" under [update], or WFP_UPDATE_CHANNEL=beta. The /download page only ever offers stable builds.

Microsoft sign-in

People can sign in to the desktop app with their Microsoft work account instead of a password, once a tenant admin has switched it on.

Switching it on. Settings → Sign-in → Microsoft Entra ID. Tick Enable Microsoft sign-in and enter the Microsoft Entra tenant ID — the Directory (tenant) ID from Azure Portal → Microsoft Entra ID → Overview. Only members of that directory can use it.

Who gets in. A person who already has an account in the workspace under the same email, or who has an open invitation to that email. Signing in with Microsoft accepts the invitation. Anyone else is refused.

On the desktop:

• The app opens the default browser on Microsoft’s sign-in page.
• The answer comes back through a listener on 127.0.0.1, on a random port. It listens on the computer itself only, and gives up after 3 minutes.
• The app keeps WorkflowPulse’s own sign-in tokens, in auth.json. It never stores Microsoft’s tokens.

The Microsoft side is one application run by WorkflowPulse, and it asks for openid, profile and email only. If your directory needs an administrator to approve new applications, ask your WorkflowPulse contact which application to approve.

The question your people will ask

What the app records, what it does not, who can see it and how long it is kept: What is recorded about you. Give people that link before the app arrives on their computer.

What your company chose to record is on Screenshots, privacy and how long data is kept.

Ask your WorkflowPulse contact

The product does not settle these, so this page does not answer them:

• Whether a code-signed Windows installer is available for your rollout
• When macOS and Linux builds will be published
• Which host serves update downloads, if your firewall needs the exact name
• Which Microsoft application to approve, if your directory needs admin consent
• Where the server and its data are hosted

Next: Inviting your people · Quick start for admins