> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefluency.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#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)

```plaintext theme={null}
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:

```plaintext theme={null}
Start-Process "$env:LOCALAPPDATA\Fluency Agent\fluency-agent.exe"  # Per-user
```

macOS:

```plaintext theme={null}
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

```plaintext theme={null}
# 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:**

1. We generate a secure setup link for your identity team.
2. Your team opens the guided portal and configures the SSO connection directly — with step-by-step instructions specific to their identity provider.
3. 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:

````plaintext theme={null}
  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](mailto:oliver@usefluency.com)

We will get back to you as soon as possible.