IT - Deploying Fluency Agent

Everything your team needs to deploy, configure, and support the Fluency Agent across your organization.

Deployment Overview

The Fluency Agent is a lightweight desktop application (~15MB) for macOS and Windows. It captures work activity — periodic screenshots and application metadata — to power Fluency’s work intelligence platform. Recommended deployment method: your existing software distribution system (Intune, SCCM, Jamf, Kandji, Munki, etc.). Self-service download by end users is not recommended. Download endpoint: https://api.usefluency.com

Quickstart Checklist

1. Install the Agent

Download from https://api.usefluency.com
Deploy via your MDM/software distribution tool (Intune, SCCM, Jamf, Kandji, etc.)
Windows: silent install with Fluency-Agent-setup.exe /S (per-user) or Fluency-Agent-Machine-setup.exe /S (per-machine) — see the Installer & Packaging section below for which one fits your fleet
macOS: deploy .app to /Applications/
Grant required permissions (Screen Recording + Accessibility on macOS; see Device Permissions)

2. Configure SSO

We send your identity team a secure setup link
They configure SSO directly in the portal — no certificate exchange needed
Supports Okta, Azure AD / Entra ID, Google Workspace, OneLogin, and any SAML 2.0 IdP
Optional: enable SCIM for automated user provisioning

3. Allowlist Network Traffic

Allowlist as detailed below

4. Verify

Deploy to test user/s
Fluency team will confirm success
Roll out to remaining users

System Requirements

Platform	Minimum Version	Architecture
macOS	14.0 (Sonoma)	Universal (Apple Silicon + Intel)
Windows	10	x64

No runtime dependencies — all dependencies are bundled. No .NET, Node.js, or other runtimes required. Storage footprint: ~15MB application + config and logs (logs rotate daily with 3 days retained; total size varies with activity volume, no fixed cap).

Installer & Packaging

macOS

Attribute	Value
Format	DMG (Disk Image)
Code Signed	Yes (Apple Developer certificate)
Notarized	Yes
Default Install Path	`/Applications/Fluency Agent.app`
Installation Scope	Per-user
Bundle Identifier	`com.fluency.fluency-agent`

Windows

Windows ships as two separate installer builds. Pick one per fleet — see Agent Updates for why the choice matters for update management. Per-user (Fluency-Agent-setup.exe)

Attribute	Value
Format	NSIS executable (.exe)
Code Signed	Yes (DigiCert, SHA256)
Default Install Path	`%LOCALAPPDATA%\Fluency Agent`
Installation Scope	Per-user
Elevation to install	No
Elevation to update	No
Supports `/DISABLEAUTOUPDATE`	No

Per-machine (Fluency-Agent-Machine-setup.exe)

Attribute	Value
Format	NSIS executable (.exe)
Code Signed	Yes (DigiCert, SHA256)
Default Install Path	`C:\Program Files\Fluency Agent\`
Installation Scope	Per-machine
Elevation to install	Yes
Elevation to update	Yes (can surface UAC for standard users)
Supports `/DISABLEAUTOUPDATE`	Yes

Silent Installation (Windows)

Fluency-Agent-setup.exe /S                  # Per-user
Fluency-Agent-Machine-setup.exe /S          # Per-machine

Use /D=<path> for a custom install directory.

Starting the Agent Immediately

By default, the agent starts automatically at the next user login. To start it immediately after installation: Windows:

Start-Process "$env:LOCALAPPDATA\Fluency Agent\fluency-agent.exe"    # Per-user
Start-Process "C:\Program Files\Fluency Agent\fluency-agent.exe"     # Per-machine

macOS:

open "/Applications/Fluency Agent.app"

Device Permissions

Permissions should be pre-granted via MDM profile (macOS) or Group Policy (Windows) to avoid user prompts.

macOS

Permission	Required	Purpose
Screen Recording	Yes	Screenshot capture via ScreenCaptureKit
Accessibility	Yes	Global event monitoring (mouse clicks, active app detection)
Full Disk Access	No	Not required
Microphone / Camera	No	Not required

Windows

Permission	Required	Purpose
UI Automation Access	Yes	Window/app detection via Windows Accessibility API
Screen Capture	Yes	Screenshot capture
Admin Rights	Install only	Per-machine installation requires elevation

Background Behavior

The agent runs in the background with a system tray icon (login/logout, recording status, settings, quit). macOS: LaunchAgent at ~/Library/LaunchAgents/com.fluency.fluency-agent.plist — starts on user login. Windows: Registry startup entry at HKCU\Software\Microsoft\Windows\CurrentVersion\Run — starts on user login. No kernel extensions, system extensions, or drivers are installed.

Network Configuration

The Fluency Agent communicates with our cloud services over HTTPS (port 443). Because the agent doesn’t run in the browser, environments with egress filtering will need to allowlist the following endpoints.

Core Fluency Services

Domain	Purpose
`api.usefluency.com`	Main API server
`vision-api.usefluency.com`	Screenshot upload and processing
`authentication.usefluency.com`	OAuth authentication (via WorkOS)
`app.usefluency.com`	Web application (opened in browser)
`dashboard.usefluency.com`	Vision dashboard (opened in browser)
`usefluency.com`	Marketing site and downloads
`support.usefluency.com`	Support portal

Regional routing: The agent supports regional API endpoints using the pattern {region}.api.usefluency.com and {region}.vision-api.usefluency.com. Default region is ap-southeast-2 (no prefix). Use wildcard *.api.usefluency.com and *.vision-api.usefluency.com to cover all regions.

Auto-Updates

Domain	Purpose
`flustack-v2-production-agent-releases.s3.ap-southeast-2.amazonaws.com`	Agent update files and metadata

Third-Party Services

Domain	Protocol	Purpose
`us.posthog.com`	HTTPS	Product analytics
`*.usepylon.com`	HTTPS	Customer support chat widget
`pylon-avatars.s3.us-west-1.amazonaws.com`	HTTPS	Support widget avatars
`*.pusher.com`	WSS (WebSocket)	Real-time communication
`fonts.googleapis.com`	HTTPS	Google Fonts
`fonts.gstatic.com`	HTTPS	Google Fonts assets

Custom URL Scheme

The agent registers fluency-agent:// for OAuth callback redirects during the SSO login flow.

Quick Copy — Firewall Allowlist

# Core (wildcard covers regional routing)
*.usefluency.com
*.getfluency.com.au

# Auto-updates
flustack-v2-production-agent-releases.s3.ap-southeast-2.amazonaws.com

# Third-party
us.posthog.com
*.usepylon.com
pylon-avatars.s3.us-west-1.amazonaws.com
*.pusher.com
fonts.googleapis.com
fonts.gstatic.com

SSO & User Provisioning

Fluency supports SAML 2.0 / SSO via WorkOS. Configuration is self-service — no certificate exchange required. How it works:

We generate a secure setup link for your identity team.
Your team opens the guided portal and configures the SSO connection directly — with step-by-step instructions specific to their identity provider.
Users sign in with their existing corporate credentials.

Supported identity providers: Okta, Azure AD / Entra ID, Google Workspace, OneLogin, and any SAML 2.0 compliant IdP. SCIM provisioning is available for automated user lifecycle management (onboarding, offboarding, group sync). Directory Sync and Log Streams can be enabled on request for organizations that require them. MFA can be enabled or disabled for your organization on request.

Data & Privacy

What Fluency captures:

Screenshots of the active monitor
Application metadata (app name, window title, timestamps, mouse activity)

Capture model: event-based, not interval-based — the agent captures on user click activity rather than on a fixed timer. Typical volume is roughly 3,000–4,000 events per active user per day, with each event (a full-resolution screenshot plus metadata) around 0.5MB. What Fluency does not capture:

No keylogging
No audio or video recording
No file system access

Local data storage:

Data	Location (macOS)	Location (Windows)	Encrypted
Config (device ID, region)	`~/Library/Application Support/com.fluency.fluency-agent/`	`%APPDATA%\Fluency\Fluency Agent\`	No
Access tokens	macOS Keychain	Windows Credential Manager	Yes
Log files (daily rotation, 3 days retained)	`~/Library/Logs/com.fluency.fluency-agent/`	`%APPDATA%\Fluency\Fluency Agent\logs\`	No
Screenshots	Not persisted locally — uploaded immediately	Not persisted locally — uploaded immediately	N/A

Agent Updates

The Fluency Agent updates automatically and silently. It checks once immediately at launch (before sign-in), then every 5 minutes thereafter, downloads any update in the background, and applies it with an automatic relaunch. No user interaction is required. To manage updates yourself, the per-machine installer only supports a /DISABLEAUTOUPDATE flag that turns the built-in update check off — roll out new versions through your MDM instead. This is recommended for per-machine fleets: applying an update in Program Files requires elevation, which can surface a UAC prompt for standard users.

The per-user installer does not support /DISABLEAUTOUPDATE — there is no installer flag to disable auto-update on per-user installs. If your fleet needs update control, use the per-machine installer, or block updates at the network level (below).

Network-level alternative for per-user fleets: the update check fails silently and safely if it can’t reach its endpoint — the agent keeps running the current version with no crash or degraded behavior. Blocking egress to flustack-v2-production-agent-releases.s3.ap-southeast-2.amazonaws.com (the same domain listed under Auto-Updates below) prevents any agent on that network from updating. Note this is domain-level, not variant-specific: it blocks per-machine and macOS agents on the same network too, since all variants share this domain (only the URL path differs). If you need to freeze updates for per-user Windows agents only, without affecting other variants, that requires a proxy capable of per-path filtering, or use the per-machine installer instead. Version pinning beyond this is not currently supported; contact us if your environment requires it. The updater always installs the latest version directly — agents that have been offline for a while do not need to step through intermediate versions. A dedicated email notification channel for security-relevant agent updates is available on request — contact us to be added.

MDM Deployment Notes

macOS (Jamf, Kandji, etc.)

Deploy the .app bundle to /Applications/
Pre-approve Screen Recording and Accessibility via a PPPC (Privacy Preferences Policy Control) profile targeting bundle identifier com.fluency.fluency-agent

Windows (Intune, SCCM, etc.)

Deploy the NSIS installer with the /S flag for silent installation
For a fully hidden rollout — no agent window ever appearing on user machines — use the per-machine installer with the /STARTHIDDEN flag; see Silent Startup on Windows

Troubleshooting tip: Most deployment issues are related to network allowlisting. If the agent installs but doesn’t connect, check your firewall rules against the allowlist above.

Common Deployment Issues

These issues come up repeatedly in real deployments. Check them proactively before you encounter them.

Issue	Prevention
Shared or service accounts used for installs	Each user must sign in with their own account. Shared or service accounts prevent Fluency from distinguishing between users, activity from multiple people will appear as a single user.
App not assigned in your identity provider	After SSO is configured, users must also be assigned to the Fluency application in your IdP (Enterprise Applications in Entra, App Assignments in Okta or Google Workspace). Without this assignment, users are blocked at sign-in even when SSO itself is configured correctly.
SSO only covers one email domain	If your organization uses more than one email domain (subsidiaries, acquired brands), notify us in advance so SSO is configured to cover all of them, not only the parent domain.
Previously trialed Fluency	If your organization has run a Fluency trial or proof of concept before, notify us before this deployment begins. Prior trial data affects how your account and SSO are configured.
Firewall or SSL inspection blocks agent traffic	The Agent uses certificate pinning, so TLS/SSL inspection must exclude Fluency’s domains (see the allowlist above). Test connectivity on a single device before deploying broadly.
macOS permissions not pre-approved	Screen Recording and Accessibility must be pre-approved via a PPPC profile before rollout. Without one, each user is prompted individually to grant permissions.
Windows endpoint security blocks the Agent	Some Microsoft Defender Attack Surface Reduction (ASR) configurations block the Agent. Deploy to a single test device first to catch this before a full rollout.
Third-party IT or MSP handling the install	If a managed service provider or contractor is performing the installation, share this guide with them directly and confirm their deployment method before rollout.
Observation window not set	If the Agent should be active only during specific hours (for example, 9am to 5pm), confirm the desired timezone and hours with your Fluency contact before go-live. This is configured by the Fluency team, not inferred automatically by the Agent.
Blacklist rules don’t match apps running inside a VM	The Agent identifies applications by what’s visible on the host. An Agent running on the host OS cannot see or match application blacklist rules against apps running inside a VM. If blacklist enforcement is needed for in-VM applications, install the Agent (per-user) inside the VM itself. There is no licensing restriction on running the Agent inside a VM.

Uninstall

The Fluency Agent can be removed through standard methods: your MDM/deployment tool, macOS drag-to-trash, or Windows Add/Remove Programs. The LaunchAgent (macOS) or registry startup entry (Windows) is removed on uninstall. No residual services or background processes remain.

Intune Example (Per-user):

  Property: Installer
  Value: Fluency-Agent-setup.exe
  ────────────────────────────────────────
  Property: Silent install flag
  Value: /S (standard NSIS)
  ────────────────────────────────────────
  Property: Install path
  Value: %LOCALAPPDATA%\Fluency Agent
  ────────────────────────────────────────  
  Property: Executable
  Value: fluency-agent.exe
  ────────────────────────────────────────
  Property: Uninstaller
  Value: %LOCALAPPDATA%\Fluency Agent\uninstall.exe
  ────────────────────────────────────────
  Property: Uninstall registry
  Value: HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\Fluency Agent_*
  ────────────────────────────────────────
  Property: Intune context
  Value: User context (not system — required for currentUser mode)
  Install script (install.ps1)

# Packaging for Intune

Intune requires `.intunewin` format — raw `.exe` files cannot be uploaded directly.

1. Download the [Microsoft Win32 Content Prep Tool](https://github.com/Microsoft/Microsoft-Win32-Content-Prep-Tool)
2. Package the installer:
   ```
   IntuneWinAppUtil.exe -c <source_folder> -s Fluency-Agent-setup.exe -o <output_folder>
   ```
3. Upload the resulting `.intunewin` file to Intune

# Silent install Fluency Agent (per-user)
  $installerPath = Join-Path $PSScriptRoot "Fluency-Agent-setup.exe"
  Start-Process -FilePath $installerPath -ArgumentList "/S" -Wait -NoNewWindow

  Uninstall script (uninstall.ps1)

  # Silent uninstall Fluency Agent (per-user)
  $uninstaller = Join-Path $env:LOCALAPPDATA "Fluency Agent\uninstall.exe"

  if (Test-Path $uninstaller) {
      Start-Process -FilePath $uninstaller -ArgumentList "/S" -Wait -NoNewWindow
  }

  Detection rule (for Intune to verify installation)

  Either file-based or registry-based:

  - File: Check existence of %LOCALAPPDATA%\Fluency Agent\fluency-agent.exe
  - Registry: Check HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\Fluency
  Agent_* exists

For a per-machine Intune package (install path C:\Program Files\Fluency Agent, Fluency-Agent-Machine-setup.exe, system context), see the Intune Notes section of the Silent Startup guide.

Support & Contacts

Oliver Farnill (CPO) oliver@usefluency.com We will get back to you as soon as possible.

Next up: enable zero-touch login on Entra-joined Windows devices with Silent Authentication via Microsoft Entra ID.

Getting Started

IT Setup

Admin Setup

Work Explorer

Opportunities

Initiatives

Product Updates

IT - Deploying Fluency Agent

Deployment Overview

Quickstart Checklist

1. Install the Agent

2. Configure SSO

3. Allowlist Network Traffic

4. Verify

System Requirements

Installer & Packaging

macOS

Windows

Silent Installation (Windows)

Starting the Agent Immediately

Device Permissions

macOS

Windows

Background Behavior

Network Configuration

Core Fluency Services

Auto-Updates

Third-Party Services

Custom URL Scheme

Quick Copy — Firewall Allowlist

SSO & User Provisioning

Data & Privacy

Agent Updates

MDM Deployment Notes

macOS (Jamf, Kandji, etc.)

Windows (Intune, SCCM, etc.)

Common Deployment Issues

Uninstall

Intune Example (Per-user):

Support & Contacts

​Deployment Overview

​Quickstart Checklist

​1. Install the Agent

​2. Configure SSO

​3. Allowlist Network Traffic

​4. Verify

​System Requirements

​Installer & Packaging

​macOS

​Windows

​Silent Installation (Windows)

​Starting the Agent Immediately

​Device Permissions

​macOS

​Windows

​Background Behavior

​Network Configuration

​Core Fluency Services

​Auto-Updates

​Third-Party Services

​Custom URL Scheme

​Quick Copy — Firewall Allowlist

​SSO & User Provisioning

​Data & Privacy

​Agent Updates

​MDM Deployment Notes

​macOS (Jamf, Kandji, etc.)

​Windows (Intune, SCCM, etc.)

​Common Deployment Issues

​Uninstall

​Intune Example (Per-user):

​Support & Contacts

Deployment Overview

Quickstart Checklist

1. Install the Agent

2. Configure SSO

3. Allowlist Network Traffic

4. Verify

System Requirements

Installer & Packaging

macOS

Windows

Silent Installation (Windows)

Starting the Agent Immediately

Device Permissions

macOS

Windows

Background Behavior

Network Configuration

Core Fluency Services

Auto-Updates

Third-Party Services

Custom URL Scheme

Quick Copy — Firewall Allowlist

SSO & User Provisioning

Data & Privacy

Agent Updates

MDM Deployment Notes

macOS (Jamf, Kandji, etc.)

Windows (Intune, SCCM, etc.)

Common Deployment Issues

Uninstall

Intune Example (Per-user):

Support & Contacts