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
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 + ~55MB maximum local data (config + logs).

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

Attribute	Value
Format	NSIS executable (.exe)
Code Signed	Yes (DigiCert, SHA256)
Default Install Path	`C:\Program Files\Fluency Agent\`
Installation Scope	Per-user

Silent Installation (Windows)

Fluency-Agent-Setup.exe /S

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

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

A Swift helper binary (event-capture-macos-sidecar) handles screen capture and event monitoring. It communicates with the main app via Unix socket and inherits the app’s permissions.

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)

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 (max 50MB)	`~/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. Updates are checked every 5 minutes (with an initial check 10 seconds after launch), downloaded in the background, and applied with an automatic relaunch. No user interaction is required. IT-controlled update management (disabling updates, pinning versions) is not currently supported. If your environment requires this, please contact us.

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

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

Added section, from real deployments, worth checking 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.

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:

  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

Support & Contacts

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

​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:

​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:

Support & Contacts