# IT rollout

Install OpenChatly Capture on many Windows, macOS and Linux computers with one enrollment token. Each computer enrolls and records on its own, with no sign-in to OpenChatly, and you link it to a person when you want.

Canonical page: https://openchatly.com/docs/capture/rollout

IT installs OpenChatly Capture, the separate recorder app, on every Windows, macOS
or Linux computer with one command. The installer adds a machine service. At
each sign-in the service enrolls the computer and starts recording. Nobody signs
in to OpenChatly by hand, and nobody needs an OpenChatly account. The service restarts the
recorder within seconds when it stops.

This page is for the IT team and the OpenChatly workspace admins. For one person on
their own computer, see [Capture → Install OpenChatly Capture](/docs/capture#install-kortix-capture).

## How it works

1. A workspace admin creates an **enrollment token** in OpenChatly.
2. IT installs `KortixCapture-x64.msi` on each computer with the OpenChatly URL and the
   token. The installer writes both to the registry and starts the
   **OpenChatly Capture** Windows service.
3. At each Windows sign-in the service reads the person's Windows sign-in
   name (the user principal name, for example `jane@corp.example`) and enrolls
   the computer with the token.
4. The computer gets a device token and starts recording. It belongs to the
   workspace. A personal token links it to its person. Any other computer
   records **linked to no one**, which is a normal state: an admin links it to
   a person when that is wanted.
5. The OpenChatly Capture icon in the notification area shows that it records.
   Nothing else interrupts the person. When the policy sets a notice, the
   person sees it once.

The service runs as `LocalSystem`. It starts the recorder in each signed-in
session as that person, and starts it again within seconds when it stops.
The enrollment token stays with the service: the registry key that holds it is
readable by SYSTEM and administrators only, and the person's processes never
see it.

## Before you start

- Turn on Capture for the workspace and set the policy: what is recorded, the
  frame rate, exclusions, retention and **the notice** the person sees. See
  [Capture → The policy](/docs/capture#the-policy).
- People do not need OpenChatly accounts. A computer records for the workspace
  whether or not it is linked to a person. To link computers to members as
  they enroll, turn on **Approve each computer**: OpenChatly suggests the member
  with the computer's sign-in email, and you confirm it.
- You need the `capture.manage` permission. Workspace owners and admins have it.

## 1. Create an enrollment token

In OpenChatly, open **OpenChatly Capture** → **Devices**, then **Company install**. Create a token and fill in:

| Field | What it does |
|---|---|
| Name | A name for the token, for example the computer group. |
| For | **Anyone at the company**: one token for many computers. They enroll linked to no one; you link them, or confirm the suggested member with **Approve each computer**. **A member**: a personal token. Every computer it installs links to that person, whoever signs in. It stops working when that person leaves the workspace. |
| Email domains | Anyone tokens only. Only people who sign in to the computer with these domains enroll. Empty: anyone. |
| Computer limit | A cap in case the token leaks. A personal token starts at 1. Empty: no limit. |
| Valid for | 7, 30 or 90 days, or **Never**. Computers enrolled before it expires keep recording. |
| Approve each computer | Every new computer waits for an admin, also when its person is a member. |

OpenChatly shows the token (`kortix_enr_…`) once. Copy it with the install
command next to it. Anyone who has the token can enroll computers into the
workspace until you revoke it, so handle it like a password.

From the API: `POST /v1/accounts/<account_id>/capture/enrollment-tokens` with
`{"name": "Pilot laptops", "email_domains": ["corp.example"], "max_devices": 20}`.
For a personal token, add `"user_id": "<member>"`: the member must belong to the
workspace, else the API answers `400` `capture_enrollment_invalid`.

## 2. Install on each Windows computer

On one computer, open **Command Prompt as administrator** and paste the line
from **Devices** → **Company install** (the dialog **Install on company computers**). It downloads the
installer, installs it silently, waits, checks that the OpenChatly Capture service
exists, and prints whether it worked:

```bat
curl.exe -fsSL -o "%TEMP%\KortixCapture-x64.msi" https://github.com/kortix-ai/CompanyOS/releases/latest/download/KortixCapture-x64.msi && start /wait msiexec /i "%TEMP%\KortixCapture-x64.msi" /qn /l*v "%TEMP%\KortixCapture-install.log" KORTIX_URL=https://api.kortix.com ENROLLMENT_TOKEN=kortix_enr_... && sc query KortixCapture >nul 2>&1 && echo Kortix Capture installed. It records from the next Windows sign-in. || echo Install failed. Log: "%TEMP%\KortixCapture-install.log"
```

`msiexec` on its own returns at once and installs in the background, and with
`/qn` it shows no error, also when the MSI path is wrong. `start /wait` and the
log make the result visible. With the MSI next to the command (Intune, a
script), the short form is:

```bat
msiexec /i KortixCapture-x64.msi /qn KORTIX_URL=https://api.kortix.com ENROLLMENT_TOKEN=kortix_enr_...
```

`KORTIX_URL` is the address of your OpenChatly API without `/v1`. Self-hosted
OpenChatly uses its own API address. The installer marks `ENROLLMENT_TOKEN` as
hidden, so it does not appear in installer logs.

With Microsoft Intune, add the MSI as a line-of-business or Win32 app and use
the command line above. With Group Policy or another tool, install the MSI
without properties and write the two registry values yourself:

| Key | Value | Type |
|---|---|---|
| `HKLM\SOFTWARE\Policies\Kortix\Capture` | `Url` | `REG_SZ` |
| `HKLM\SOFTWARE\Policies\Kortix\Capture` | `EnrollmentToken` | `REG_SZ` |

An upgrade (`msiexec /i` with a newer MSI) keeps the registry values when you
pass no properties.

The installer never rolls back because the service did not start: it starts the
service when it can, and Windows starts it about a minute after every boot. The
MSI installs the Microsoft Edge WebView2 Runtime when a Windows 10 computer does
not have it; the OpenChatly Capture window needs it. A person who double-clicks the
MSI without properties gets the app opened at the end and signs in from it.

## 3. Check the rollout

**Devices** lists every enrolled computer with an **IT rollout**
badge, under its person or under **Linked to no one**, with its live state:
recording, paused, offline. A computer reports within a minute of the first
Windows sign-in.

To link a computer to a person, choose **Link to a person…** on it. What it
recorded linked to no one moves to that person. See
[Capture → Link a computer to a person](/docs/capture#link-a-computer-to-a-person).

**Waiting for approval** lists computers that wait for an admin: the token
approves each computer, or an admin revoked this one. For each, choose
**Approve** (and, if you like, the person it records for) or **Deny**. An
approved computer starts recording within a minute.

On the computer:

```powershell
sc query KortixCapture
Get-Process kortix-capture | Select-Object Id, SessionId
```

The service is `RUNNING`, and a `kortix-capture` process runs in each
signed-in session.

## What Kortix Capture costs a computer

Kortix Capture runs below normal priority and, on Windows 11, in efficiency
mode, so the apps a person works in always win the CPU. The keyboard and mouse
hook never waits on Capture's own work.

- **With record only included apps** (for example only the apps a team works in),
  Capture takes no screenshots, reads no text and walks no app's accessibility
  tree while another app is in front.
- **While a person works**, Capture defers what can wait: text recognition
  reads each screen at most every 30 seconds, and video encoding waits for a
  pause (at most 5 minutes).
- **Text recognition can be off.** In Kortix, **Capture → Settings → Screen
  frames → Text recognition → Off** reads no screen text on any computer: the
  least CPU. Search then finds apps, window titles and URLs.
- **On a slow computer**, Capture slows itself down: a capture or a text read
  that takes longer is followed by a longer rest, so screen capture uses at most
  half and text recognition at most a fifth of one core.
- **Device details** in **Devices** shows what Capture used on each computer in
  the last 10 minutes: CPU (average and peak, as a share of one core), memory,
  and each Capture process.

Antivirus scans each new file. To keep that scanning off the recorder, exclude
the library folder `%APPDATA%\ai.kortix.capture` and the processes
`kortix-capture.exe`, `kortix-capture-engine.exe` and `kortix-backend.exe`
(Microsoft Defender: Intune → Endpoint security → Antivirus → exclusions).

## Remove a computer or stop a rollout

| To | Do |
|---|---|
| Stop new computers from enrolling | Revoke the token in **Company install**. Enrolled computers keep recording. |
| Stop one computer | Revoke the device in **Devices**, or deny it in **Waiting for approval**. Its device token stops working at once. The computer does not enroll again until an admin approves it. |
| Remove OpenChatly Capture | `msiexec /x KortixCapture-x64.msi /qn` (the same MSI), or **Settings → Apps → OpenChatly Capture → Uninstall**. The service and the program files go away. Recordings on the computer stay in each person's profile until retention deletes them. |

## What the enrollment token can and cannot do

- It enrolls computers into one workspace, within its domains, limit and
  expiry. It cannot read anything.
- A device token, which each enrolled computer gets, uploads that computer's
  recordings and reads the workspace's policy. It cannot read recordings.
- The sign-in name a computer reports is not proof of who uses it: an
  administrator of that computer can change it. So the name never links a
  computer on its own. It is a suggestion you confirm under **Approve each
  computer**.
- An enrolled computer proves itself with its current device token when it
  enrolls again. A copy of its machine key alone gets a new token only after
  an admin approves it, for example after a reinstall.
- Every enrollment, token change and decision is in the workspace's audit log:
  `capture.device.enroll`, `capture.enrollment_token.create`,
  `capture.enrollment_token.revoke`, `capture.enrollment.approve`,
  `capture.enrollment.deny`, `capture.device.link`.

## Answers from enroll

The service writes these answers to its log (`%ProgramData%\Kortix\Capture\logs`)
and asks again on its own.

| Answer | Means | The computer |
|---|---|---|
| `enrolled` | The token is valid. `member` names the linked person, or is `null` while the computer is linked to no one. | records |
| `pending` `approval_required` | The token approves each computer, an admin revoked this one, or it asked for a new token without its current one. | waits; asks again every minute |
| `401` `enrollment_token_invalid` | The token is unknown, revoked or expired. | asks again every hour |
| `403` `enrollment_domain_not_allowed` | The sign-in domain is not one of the token's. | asks again every 6 hours |
| `403` `enrollment_limit_reached` | The token reached its computer limit. | asks again every hour |
| `403` `enrollment_denied` | An admin denied this computer. | asks again every 6 hours |
| `403` `capture_disabled` | Capture is off for the workspace. | asks again every hour |

## macOS

IT writes the OpenChatly URL and the token to a root-only file, then installs the
package. The package installs `Kortix Capture.app` (Developer ID signed and
notarized), a machine service (LaunchDaemon) that holds the token and enrolls
each person who signs in, and an agent that records in every session.

```bash
sudo mkdir -p "/Library/Application Support/Kortix/Capture"
echo '{"url":"https://api.kortix.com","enrollment_token":"kortix_enr_..."}' | sudo tee "/Library/Application Support/Kortix/Capture/config.json" >/dev/null
sudo chmod 600 "/Library/Application Support/Kortix/Capture/config.json"
curl -fsSL -o /tmp/KortixCapture-universal.pkg https://github.com/kortix-ai/CompanyOS/releases/latest/download/KortixCapture-universal.pkg && sudo installer -pkg /tmp/KortixCapture-universal.pkg -target / && echo "Kortix Capture installed."
```

With an MDM, deploy the package and a configuration profile for the domain
`ai.kortix.capture` with the keys `Url` and `EnrollmentToken`. A profile is
readable by every user on the computer; use the root-only file when the token
must stay secret.

macOS asks the person to allow Screen Recording once. A Privacy Preferences
Policy Control (PPPC) profile can pre-approve Accessibility and Input
Monitoring for `ai.kortix.capture`; for Screen Recording it can only let a
standard user approve it. To remove OpenChatly Capture:
`sudo "/Applications/Kortix Capture.app/Contents/Resources/uninstall.sh"`.

## Linux

```bash
sudo install -d -m 755 /etc/kortix
echo '{"url":"https://api.kortix.com","enrollment_token":"kortix_enr_..."}' | sudo tee /etc/kortix/capture.json >/dev/null
sudo chmod 600 /etc/kortix/capture.json
curl -fsSL -o /tmp/kortix-capture_amd64.deb https://github.com/kortix-ai/CompanyOS/releases/latest/download/kortix-capture_amd64.deb && sudo apt-get install -y /tmp/kortix-capture_amd64.deb && echo "Kortix Capture installed."
```

The package installs a machine service (`kortix-capture-machine`) that holds
the token and enrolls each person who signs in to a graphical session, and a
user service that records in every session. OpenChatly Capture records X11
sessions; a Wayland session enrolls but records nothing yet. To remove it:
`sudo apt purge kortix-capture`.

Without the config file on macOS or Linux, each person chooses
**Sign in with OpenChatly…** from the OpenChatly Capture icon
([Capture → Install OpenChatly Capture](/docs/capture#install-openchatly-capture)).
