Capture
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
403withcode: "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 |
Download the installer for the computer: Windows
(.msi), macOS (.pkg) or
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 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:
- Install OpenChatly Capture and open it from the OpenChatly Capture icon.
- Choose Sign in with OpenChatly…. The browser opens
/capture/authorizewith a code. Check that the code matches, then choose the workspace. Only workspaces with Capture on are listed. - 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 local time;
- retention: In OpenChatly is how many days OpenChatly keeps recordings (
remote_days, default 90,0keeps 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.
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) |
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:
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).
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 for the client
surface and the React hooks.