---
title: Capture
description: Record each member's screen, input actions and audio 24/7 into a searchable timeline that belongs to the OpenChatly workspace.
---

OpenChatly Capture records a member's own computer all day, so you can find and replay anything that happened on screen. It records three layers:

- the screen: video, the app, the window title, the URL and the on-screen text;
- input actions (clicks, typing), each with a screenshot;
- audio, with a transcript, when the workspace's policy turns it on.

OpenChatly uploads the recordings, indexes them into one timeline per person, and lets you rewatch and search any moment.

Capture belongs to the OpenChatly workspace. One workspace has one Capture setup: one switch and one policy. Every computer signs in to the workspace.

## Turn Capture on

A person with the `capture.manage` permission turns Capture on for the
workspace. Workspace owners and admins have it. Capture is off by default. While
it is off:

- every Capture route answers `403` with `code: "capture_disabled"`;
- a device cannot sign in or get storage credentials;
- OpenChatly indexes nothing new.

OpenChatly Capture has its own area at `/capture`. Open **OpenChatly Capture** from
the command palette (or go to `/capture`), choose **Settings**, and turn on
**OpenChatly Capture** for the organization. The same page holds the organization's
rules: what computers record, how long OpenChatly keeps it, where it is stored, an
workspace-wide pause and an optional notice. The area also has **Devices** and
**Timeline**.

From the API: `PATCH /v1/accounts/<account_id>/capture` with `{"enabled": true}`.
From TypeScript: `kortix.capture.account(accountId).workspace.setEnabled(true)`.

## Install OpenChatly Capture

OpenChatly Capture is its own app, installed apart from the OpenChatly app. It runs in
the background on Windows, macOS and Linux, shows an icon in the notification
area (the menu bar on macOS), and records into one OpenChatly workspace. A computer
connects in one of two ways:

| Way | For | How |
|---|---|---|
| Sign in with OpenChatly | one person on their own computer | the person approves the computer in the browser |
| Enrollment token | IT, for many computers at once | IT installs with a token; nobody signs in. See [IT rollout](/docs/capture/rollout) |

Download the installer for the computer: [Windows](/download/capture/windows)
(`.msi`), [macOS](/download/capture/macos) (`.pkg`) or
[Linux](/download/capture/linux) (`.deb`). The same links are in **Devices** under
**Get OpenChatly Capture**.

Every OpenChatly release carries the installers, under the same version. The
[releases page](https://github.com/kortix-ai/CompanyOS/releases/latest) lists them
with their checksums in `CAPTURE-SHA256SUMS`. A computer with the machine service
(every installer) updates itself: it checks for a signed release every 6 hours,
installs it, and goes back to the previous version when the new one does not record.
To update by hand, install a newer installer over the old one. The configuration stays.

To sign in with OpenChatly:

1. Install OpenChatly Capture and open it from the OpenChatly Capture icon.
2. Choose **Sign in with OpenChatly…**. The browser opens `/capture/authorize`
   with a code. Check that the code matches, then choose the workspace. Only
   workspaces with Capture on are listed.
3. On macOS, grant the permissions when asked: Screen Recording for the
   screen, Accessibility and Input Monitoring for actions, Microphone for
   audio. Windows and Linux ask for none.

Without the icon, run
`kortix-capture sync setup --provider kortix --issuer <your OpenChatly API>`.

The computer then records into that workspace as you and uploads every finished
item. It gets a revocable device token and, from it, short-lived storage
credentials for its own folder (`orgs/<account_id>/<device_id>/`) and read
access to the policy. Signing in again on the same computer reuses the device.
Forgetting a time range on the device removes it from OpenChatly too.

## Link a computer to a person

Every computer is a device in **Devices**. The list shows each device's state (**Recording**, **Paused**, **Offline**, **Needs permission** and others), its Capture version (with **Update available** or **Update failed**), when it last recorded, and a fleet summary. **Device details** in a device's `...` menu shows what the computer reports: the version, the update state and why an update failed, the OS and build, CPU, memory, free disk, sync and policy. **Copy diagnostics** copies it as text for a support request. OpenChatly sends a notification to the people who manage Capture when a computer stops recording, and again when it recovers. A computer you signed in
records for you. A computer IT enrolled with a personal token records for the
member the token names. A computer IT enrolled with a company token records for
the workspace, **linked to no one**. That is a normal state: link it to a person
only when you want it in their timeline.

To link a device, choose **Link to a person…** on it; to change the person, choose **Change linked person…** (`capture.manage`). From then on the computer records for that person. What it
recorded linked to no one moves to them within minutes; what it recorded for
an earlier person stays theirs. From the API:
`PUT /v1/accounts/<account_id>/capture/devices/<device_id>/link` with
`{"user_id": "<member>"}`, or `{"user_id": null}` to unlink.

Only people with `capture.read_all` see a computer linked to no one. Every
read of it writes `capture.device_view` to the audit log. An agent never reads
it.

## Who sees what

Access is OpenChatly IAM. Capture has no roles of its own.

| Who | Reads | Writes |
|---|---|---|
| Every member | their own devices and timeline | revokes their own devices |
| `capture.read_all` | every member's devices and timeline, and workspace-wide search | nothing |
| `capture.manage` | the workspace and the policy | the switch, the policy, revokes any device |
| An agent | only the timeline of the person its private session acts for | nothing |

Workspace owners and admins have `capture.read_all` and `capture.manage` by
default. To give either one to someone else, add it to a custom role
(**Workspace settings** → **Roles**). A OpenChatly API key acts as the person
who made it, with the same permissions.

Every read of another member's data writes `capture.member_view` to the
workspace's audit log. A workspace-wide read (all devices, workspace search) writes
`capture.account_view`. An agent's read writes `capture.agent_read`. Turning
Capture on or off writes `capture.enable` or `capture.disable`.

## The policy

One policy applies to every device of the workspace:

- layers: screen, actions, audio (audio is off until someone turns it on);
- **Apps and websites**: pick the policy type, then its list.
  - **Exclusion policy** (the default): record everything except what you
    exclude: apps, websites, categories (password managers, messaging,
    banking; **Show list** names every app and website a category covers) and
    private browsing windows.
  - **Inclusion policy**: record only the apps and websites you include. An
    included app is recorded in full; an included website in any browser.
    Everything else is blacked out. The exclusions still apply as **Never
    record, even if included**.
  - **People can add their own included apps and websites** (on by default).
    Off: computers record only your Included list. People can always add apps
    and websites to skip, because that only records less.
  - **Common apps** and **Common websites** add with one click; an app adds its
    macOS and Windows ids together and shows by name.
  - Anything skipped is blacked out, a display with nothing left to record
    writes no frame, and actions in skipped apps are not recorded. A person can
    add their own entries in OpenChatly Capture (Settings, Apps and websites) but
    cannot remove the organization's or switch an inclusion policy back.
    Audio is not filtered by app: leave the audio layer off under an inclusion
    policy;
- a workspace-wide pause;
- **Screen frames**: the resolution (720p to 4K) and text recognition
  (accurate, fast or off). Left on **Each computer decides**, a computer uses
  1440p and accurate text recognition. Set, every computer uses it and shows it
  locked. OpenChatly Capture sets the frame rate itself: up to 2 frames a second
  while someone works, one every 2 s otherwise, and fewer on a busy computer.
  Clicks, typing and scrolling are recorded with their own screenshots;
- on an organization's computer, a person's pause or off switch ends by itself
  at the next 06:00 local time;
- retention: **In OpenChatly** is how many days OpenChatly keeps recordings (`remote_days`, default 90, `0` keeps them without a limit), and **On the computer** is how many hours a computer keeps its local copy after upload (`local_hours`, default 0);
- an optional notice: each person sees it once, and again when its text changes;
- **Experimental → Privacy controls** (off by default) shows personal-data
  masking on the computer (each computer first downloads a ~1 GB model).
  Turning the switch off hides it; what is set keeps applying.

Retention is a ceiling: a person can keep recordings on their own computer for a shorter time than the policy allows, not longer. By default a computer keeps recordings that are not uploaded yet, and deletes uploaded ones after 7 days.

A computer gets the policy the moment it signs in or IT enrolls it, so a new
computer starts under your exclusion or inclusion policy with nothing to set up.
Until the policy has arrived (seconds after sign-in), the computer records
nothing. In OpenChatly Capture, Settings, Apps and websites says where its rules
come from: "Synced from" your organization with the policy type, or "Set on
this computer" when it is not synced to an organization.

OpenChatly publishes the policy to `orgs/<account_id>/policy.json` in the capture
store, where every device reads it within a minute. A device cannot write a
policy of its own. OpenChatly also enforces the layers when it indexes: a device
never widens the policy.

A device records every connected display, the active one (the display with
the focused window) first. Each display is its own recorded item; the
timeline names the display of every item and frame.

## Where recordings are stored

By default OpenChatly keeps and indexes the recordings (**OpenChatly-managed**). Under **Settings** → **Storage**, an owner or admin can point the workspace at an S3 bucket they own instead: AWS S3, or an S3-compatible store such as MinIO. OpenChatly reads, indexes and signs recordings in that bucket.

| Field | Meaning |
|---|---|
| **Endpoint** | Leave empty for AWS. For another S3-compatible store, the full URL. |
| **Region**, **Bucket** | The bucket's location and name. |
| **Path-style URLs** | On for MinIO and most self-hosted stores; off for AWS. |
| **Access** | An **IAM role (STS)** that OpenChatly assumes (recommended: each computer gets credentials for its own folder), or a static **Access key** pair (every computer gets workspace-wide access to the bucket). |

OpenChatly writes a test object before it saves the choice. Switching does not move recordings that are already stored. Client-side encryption on a computer is incompatible with indexing: a recording a computer encrypts cannot be searched or played in OpenChatly. From the API: `GET` and `PUT /v1/accounts/<account_id>/capture/storage` (`capture.manage`). On a self-hosted OpenChatly, see [Self-hosting](/docs/developers#self-hosting).

## OpenChatly Capture API

Everything Capture records is readable with an OpenChatly API key, from a script, a
notebook, a BI tool or an agent.

**Auth.** Create a key in OpenChatly (**Settings** → **Personal access keys**, or **Create an API key** in the **OpenChatly Capture API** dialog on **Devices**) or with
`POST /v1/accounts/tokens`. Send it as `Authorization: Bearer kortix_pat_…`.

**Base URL.** `https://<your OpenChatly API>/v1/accounts/<account_id>/capture`.
`GET /v1/accounts` lists your accounts.

**Scoping.** Every route reads your own data by default. With
`capture.read_all`, pass `user_id=<member>` (audited as `capture.member_view`)
or, where the route takes it, `scope=account` for every member (audited as
`capture.account_view`). A device linked to no one is read by its `device_id`
without `user_id` (`capture.read_all`, audited as `capture.device_view`);
without that permission the same request returns only your own rows of it. A
read outside your permissions answers `403`
`capture_forbidden`. While Capture is off, every route answers `403`
`capture_disabled`.

| Endpoint | Returns |
|---|---|
| `GET /` | `{ account_id, enabled, can_read_all, can_manage, updated_at }` |
| `PATCH /` `{ "enabled": true }` | the same; needs `capture.manage` |
| `GET enrollment-tokens` · `POST enrollment-tokens` · `DELETE enrollment-tokens/<token_id>` | the IT rollout tokens; needs `capture.manage` (see [IT rollout](/docs/capture/rollout)) |
| `GET enrollments?status=pending` · `POST enrollments/<id>/approve` `{ "user_id" }` · `POST enrollments/<id>/deny` | computers that wait for a decision; needs `capture.manage` |
| `PUT devices/<device_id>/link` `{ "user_id" }` | links the device to a member, or unlinks it with `null`; needs `capture.manage` |
| `POST devices/<device_id>/sync` | reads the device's status and index now and queues new items for indexing |
| `GET storage` · `PUT storage` | where the workspace keeps recordings; needs `capture.manage`; the secret is never returned |
| `GET devices?user_id=&scope=account` | devices with their live state: what the device last reported (for example `recording`, `paused`), or `offline` after 2 minutes of silence, their `health`, and `diagnostics` (OS, update state and failure reason, sync, policy, hardware) |
| `DELETE devices/<device_id>` | revokes the device: its token stops working at once |
| `GET devices/<device_id>/assets/<name>` | a signed URL of one action screenshot (5 minutes) |
| `GET policy` · `PUT policy` `{ "policy": { … } }` | the workspace policy; writing needs `capture.manage` |
| `GET days?tz=Europe/Berlin&user_id=&device_id=` | the days with recordings, newest first, in a time zone |
| `GET timeline?day=&from=&to=&user_id=&device_id=&display_id=` | `{ displays, focus, runs, chunks }`: the displays seen, which display held the focus when, app and window runs (of the focused display, or of `display_id`), and the indexed items, in a window of at most 31 days |
| `GET timeline/items?from=&to=&user_id=&device_id=&display_id=` | `{ frames, actions, audio }`, oldest first, at most 500 of each; `display_id=all` for every display |
| `GET search?q=refund or invoice&kinds=screen,actions,audio&app=&from=&to=&limit=20&scope=account` | hits, newest first: `{ kind, id, ts, user_id, device_id, chunk_id, display_id, display_name, app, title, url, snippet }` (one screen hit per chunk and window; `limit` up to 100) |
| `GET frames/<frame_id>` | `{ frame, video: { url, expires_at, offset_ms }, screenshot }`: the full on-screen text, the 1 fps chunk video to seek, the nearest action screenshot (signed URLs, 5 minutes) |
| `GET chunks/<chunk_id>/media` | signed URLs of an item's video or audio |

`user_id` resolves to a name and email through
`GET /v1/accounts/<account_id>/members`, which every member of the account may
read.

Example:

```bash
curl -s -H "Authorization: Bearer $KORTIX_API_KEY" \
  "https://<your OpenChatly API>/v1/accounts/$ACCOUNT/capture/search?q=invoice&limit=5"
```

The TypeScript SDK wraps the same routes: `kortix.capture.account(accountId)`
(see [SDK reference > `kortix.capture`](/docs/developers#kortixcapture)).

## Agents in a session

An agent in a member's private session reads that member's timeline through
`/v1/capture/me/search`, `/v1/capture/me/timeline` and
`/v1/capture/me/frames/<frame_id>`, or with `kortix capture search`,
`timeline` and `frame`. It reads only that person, in the session's account. A
trigger run or a shared session acts for no person and gets `403`
`capture_no_human`.

## Build on it

See [SDK reference > `kortix.capture`](/docs/developers#kortixcapture) for the client
surface and the React hooks.
