---
title: Device Capture and Privacy
summary: Explicit source approval, local retention, and privacy controls for device activity.
---

# Device capture and privacy

SkyKoi does not collect device activity merely because the gateway is installed or running. Device capture is disabled by default. Enabling it requires an overall switch plus an explicit source list.

```bash
export SKYKOI_CAPTURE_ENABLED=1
export SKYKOI_CAPTURE_PURPOSE="Project organization and build diagnostics"
export SKYKOI_CAPTURE_SOURCES=process,file
export SKYKOI_CAPTURE_FILE_ROOTS="$HOME/Projects"
```

The interactive login/onboarding flow can write the same policy to
`~/.skykoi/capture-policy.json` after showing a plain-language approval summary.
The file is owner-readable only. Environment variables take precedence for
managed deployments.

Supported source names are `input`, `terminal`, `process`, `file`, `browser`, `calendar`, `screen`, `notification`, `message`, and `audio`.

Choose the smallest set needed for the job. Process and approved-root file events are usually enough for operational awareness. Screen, messages, browser history, terminals, audio, and raw input can expose unrelated people and sensitive personal information.

## Raw input

Raw keyboard, mouse, clipboard, and accessibility capture is excluded even when `input` appears in the source list. It requires a second deliberate acknowledgement:

```bash
export SKYKOI_CAPTURE_RAW_INPUT_ACK=I_UNDERSTAND_RAW_INPUT_CAPTURE
```

Secure text fields are suppressed at the event-tap boundary. Raw input is intended only for a narrowly scoped, informed accessibility workflow; it is not an employee-monitoring default.

## Local persistence

Approved capture stays in memory unless local persistence is separately enabled:

```bash
export SKYKOI_CAPTURE_PERSIST=1
export SKYKOI_CAPTURE_RETENTION_DAYS=7
```

Retention is bounded from 1 to 30 days. Capture files and directories use owner-only permissions, and hot files are size-bounded. The permissioned event ledger—not the raw capture buffer—is the durable record for approved business events.

## Approved file inventory

When file capture starts, SkyKoi performs a metadata-only inventory of each approved root so existing files and folders can appear in the graph immediately. It skips symlinks and secret-like paths, reads no file content during inventory, and defaults to 10,000 files per root (`SKYKOI_CAPTURE_INITIAL_FILE_LIMIT`, capped at 100,000). Live watcher events continue after that boundary. Preview synchronization is separately approved and generated through a bounded serial queue.

## Cross-device thumbnails

File thumbnails are a separate choice from file metadata synchronization:

```bash
export SKYKOI_CAPTURE_PREVIEW_SYNC=1
```

The runtime generates a bounded WebP rendition using native preview support,
PDF/Office renderers, image decoding, or a universal fallback card. Pending
thumbnails are AES-256-GCM encrypted with a device-bound key in the local
outbox. After the signed artifact version is acknowledged, the thumbnail is
sent over the authenticated gateway route and stored in a tenant- and
version-bound encrypted envelope. The web and iOS clients still enforce graph
visibility before decrypting and returning it.

## Private mode and mute

Private mode immediately stops persistent raw-input and audio agents, stops the active capture service, and prevents new events from entering memory or disk. Turning private mode off requires a gateway restart before approved capture resumes.

Audio mute also stops the audio agent. These settings persist across gateway restarts.

Use the gateway capture status RPC or the corresponding interface to see whether policy is enabled, the approved source names, persistence state, retention, mute, and private-mode state.

## Deployment guidance

- Keep personal and managed-work device policies separate.
- Exclude password managers, secure fields, health/legal/financial apps, personal profiles, and private roots.
- Obtain the required user and organization approvals before enabling a source.
- Give users a visible way to pause, inspect, export, revoke, and delete collected information.
- Do not describe server-readable capture as end-to-end encrypted.