Security Guide for End Users

This document explains the security model, permissions, and considerations for users who clone and run CoWork OS on their machines.

Overview

CoWork OS is an AI-powered task automation tool that can execute actions on your behalf. By design, it has capabilities that require careful consideration:

• Execute shell commands
• Read and write files
• Browse the web
• Connect to external APIs

All of these capabilities are consent-based and sandboxed where possible.

CoWork OS can also expose Chronicle, an opt-in desktop recent-screen context feature. Chronicle keeps a short local passive screen buffer to resolve vague on-screen references, but it does not send those passive screenshots to external providers by itself. Chronicle is configured from Settings > Memory Hub > Chronicle, with pause/resume controls and explicit consent gating. See Chronicle.

---

Permissions Model

Workspace Permissions

Each workspace you create has configurable permissions. These are coarse capability gates; the permission engine still decides whether a specific action should be allowed, denied, or prompted.

Recommendation: Only enable shell and delete permissions for workspaces where you trust the AI to perform those operations.

Approval System

Approval prompts are now part of a layered permission engine:

• Safe reads may auto-allow when a matching mode or rule exists
• Writes, deletes, shell commands, and external side effects may prompt based on mode or rule
• Hard guardrails still block obviously dangerous commands before prompting
• Exact reasons are shown so you know whether the decision came from a rule, mode, or guardrail

You can still approve or deny each request individually, and you can persist some approvals as session, workspace, or profile rules.

For the full evaluation order, rule precedence, and persistence model, see Permission System.

Workspace Rule Management

Workspace-local permission rules are visible in Settings > System & Security for the active workspace. From there you can:

• browse workspace-local rules
• remove a rule directly
• persist new workspace rules from approval prompts

Workspace-local rule removal updates both the local SQLite row and the workspace policy manifest. If the manifest write fails, the database removal still succeeds and the app reports the partial result.

Configurable Guardrails

CoWork OS includes configurable guardrails in Settings > Guardrails to limit what the agent can do:

Dangerous Command Blocking

The following command patterns are blocked by default:

Commands are blocked before reaching the approval dialog. You can add custom patterns in Settings.

Trusted-command patterns now feed the permission engine as compatibility rules instead of acting as the final approval system.

Domain Allowlist

When enabled, browser automation is restricted to specified domains:

• Exact match: github.com
• Wildcard: *.google.com (matches subdomains)
• If enabled with no domains: all navigation blocked

This prevents unintended browsing during automation tasks.

---

What the App Can Access

File System Access

Technical details:

• Path traversal protection prevents accessing files outside the workspace
• Symlink attacks are mitigated through path normalization
• Implementation: src/electron/agent/tools/file-tools.ts

Workspace Kit Project Access Rules

If a workspace contains a .cowork/projects/<projectId>/ACCESS.md file, built-in tools enforce per-project access based on the task's assigned agent role:

• ## Allow and ## Deny sections accept agent role IDs (one per line prefixed with -).
• Use all to match every agent role.
• Deny wins over allow.

Enforcement applies to:

• File/edit/grep/search tools when the path is inside .cowork/projects/<projectId>/...
• Workspace-kit context injection (denied projects are excluded from injected context)

Important: shell commands are not subject to these per-project access rules. Keep shell permission disabled unless you explicitly need it, and review shell approvals carefully.

Shell Command Execution

When you enable shell permissions:

Security note: Your API keys and secrets are never exposed to shell commands. The app creates a minimal, safe environment for each command.

Browser Automation

The app includes Playwright for web automation:

User agent: CoWork OS Browser Automation

Chronicle Screen Context

Chronicle is separate from browser automation and from dedicated computer-use mouse/keyboard control.

Chronicle also introduces a prompt-injection risk from visible screen content. A malicious page, document, or chat window can place instructions on screen that the agent may later treat as relevant context. CoWork marks Chronicle text as untrusted screen text, but you should still keep Chronicle paused or off when viewing sensitive or untrusted material, and prefer direct source tools over screen-derived context when a file, URL, PR, or thread can be read directly.

---

Network Connections

LLM API Providers

The app connects to these services based on your configuration:

Search Providers (DuckDuckGo built-in; others optional)

Other Connections

ACP Remote Agents

Remote ACP delegation is constrained more tightly than ordinary outbound automation:

• registration is scope-gated
• non-operator clients are limited to their own ACP tasks and inbox reads by default
• remote endpoints are validated before invocation
• https is preferred, while plain http is intended only for loopback development
• private and link-local IP targets are rejected by the remote invoker validation layer
• remote requests use bounded timeouts so bad endpoints cannot hang the main process indefinitely

No Telemetry

CoWork OS does not:

• Send usage analytics
• Track user behavior
• Phone home to any server
• Share your data with third parties

Your data stays on your machine and only goes to the LLM provider you explicitly configure.

---

Data Storage

Encrypted Settings Storage (SecureSettingsRepository)

All settings are now stored encrypted in the database using the SecureSettingsRepository:

Typical userData locations:

• macOS: ~/Library/Application Support/cowork-os/
• Linux: ~/.config/cowork-os/
• Windows: %APPDATA%\\cowork-os\\

Encryption Layers

Primary: OS Keychain (when available)

• macOS: Keychain Services
• Windows: DPAPI (Data Protection API)
• Linux: libsecret

Fallback: App-Level Encryption

• AES-256-GCM encryption
• Key derived via PBKDF2 (100,000 iterations, SHA-512)
• Stable machine ID prevents key changes on hostname updates

Settings Categories

All these are stored encrypted in the database:

Data Integrity

Each stored setting includes:

• SHA-256 checksum for integrity verification
• Creation and update timestamps
• Automatic corruption detection on load

What's Stored in the Database

• Workspace configurations
• Task history, events, and logs (including task prompts and timeline messages)
• Channel/gateway configurations
• Channel message history (incoming/outgoing message content for configured channels)
• All encrypted settings (API keys, preferences, configurations)

Everything is stored locally on your machine. CoWork OS does not upload your database or message history to any CoWork OS servers.

API Key Security

Your API keys are:

1. Encrypted using OS Keychain when available (macOS Keychain, Windows DPAPI, Linux libsecret)
2. Fallback to AES-256 app-level encryption with stable machine-derived key
3. Decrypted only when needed for API calls
4. Never logged or displayed in full
5. Never passed to shell commands or subprocesses
6. Checksummed for integrity verification

Media and File Validation

CoWork also applies guardrails before certain file and media operations reach external providers:

• large text writes are blocked by the configured file-size guardrail
• binary files are rejected from text-only write paths
• video-generation reference images/videos must be absolute paths, real files, and within supported size/type limits
• external skill directories must be explicit existing absolute paths and are treated as read-only by the app

---

Electron Security Configuration

Security Settings

Content Security Policy (Production)

default-src 'self';
script-src 'self';
style-src 'self' 'unsafe-inline';
img-src 'self' data: https:;
font-src 'self' data:;
connect-src 'self' https:;
frame-ancestors 'none';
form-action 'self';

macOS Entitlements

Not requested: Camera, microphone, contacts, location, or other sensitive permissions.

---

Messaging Channel Security

If you use the gateway feature to connect messaging bots (Telegram, Discord, Slack, WhatsApp, iMessage, Signal):

Security Modes

Best Practices

1. Use pairing mode for bots accessible to others
2. Generate new pairing codes for each user
3. Revoke access for users who no longer need it
4. Don't share bot tokens publicly

---

Auto-Update Mechanism

How Updates Work

For git clones (development):

1. Checks GitHub API for new releases/commits
2. User initiates update manually
3. Runs: git pull, npm run setup, npm run build
4. Requires app restart

For packaged builds:

1. Uses electron-updater with GitHub releases
2. Downloads signed releases from official repo
3. Verifies integrity before installing

Supply Chain Considerations

Note: If you're security-conscious, review changes before updating:

git fetch origin
git diff HEAD..origin/main

---

Security Best Practices

For General Use

1. Review shell commands before approving - read what will execute
2. Use dedicated workspaces - don't point at sensitive directories
3. Enable minimal permissions - only enable what you need
4. Keep updated - security fixes come through updates
5. Protect your API keys - don't share configuration files

For Messaging Bots (Telegram/Discord/Slack/WhatsApp/iMessage/Signal)

1. Never use "open" mode for public bots
2. Use pairing codes for secure user onboarding
3. Regularly audit connected users
4. Revoke access when no longer needed
5. For Signal: Use a dedicated phone number (registration deactivates other Signal instances)

For Development

1. Review code changes before pulling updates
2. Audit dependencies periodically with npm audit
3. Don't commit .env or settings files
4. Use separate workspaces for testing

---

Threat Model

What CoWork OS Protects Against

What Requires User Vigilance

Out of Scope

• Protection against malicious LLM responses (AI safety)
• Physical access to your machine
• Compromised macOS system
• Malicious code you add to workspaces

---

Verifying Security

Check Workspace Permissions

In the app, navigate to your workspace settings to review:

• Read/Write/Delete/Shell permissions
• Workspace path scope

Audit Connected Users (Bots)

In the Gateway settings, you can:

• View all connected users
• Revoke access for specific users
• Generate new pairing codes

Review Pending Approvals

The app shows a notification badge when approvals are pending. Always review:

• The exact command to be executed
• The file to be deleted
• Any other sensitive operation

---

Reporting Security Issues

If you discover a security vulnerability:

1. Do NOT create a public GitHub issue
2. Use GitHub Security Advisories (Security tab > Report a vulnerability)
3. Include reproduction steps and impact assessment

See SECURITY.md for full details.

---

Advanced Security Framework (v0.3.8.7+)

CoWork OS includes a comprehensive security framework inspired by formal verification techniques.

Tool Groups & Risk Levels

Tools are categorized by risk level for policy-based access control:

Ordinary uploaded-PDF reading uses the local parse_document extraction path. The extracted text is still treated as untrusted document data, but it is not an export/egress operation unless the task uses read_pdf_visual or another tool that sends local bytes to an external provider.

High-autonomy modes and session "Approve all" do not silently bypass this export/egress lane.

The computer-use family (screenshot, click, type_text, keypress, and related tools on macOS and Windows) is not low-risk read-only automation: it can drive arbitrary UI the operator can reach. Treat it as high trust and keep the computer_use built-in category disabled unless you need it. See Computer use.

Computer use security

• Helper-targeted macOS permissions: Accessibility and Screen Recording are granted to the bundled helper runtime, with inline bootstrap at task time and settings shortcuts for recovery.
• Windows visible-window constraint: Windows v1 only targets visible, non-minimized windows and may require comparable privilege for elevated apps.
• Safety UX: Active sessions use a single-session lock, Esc abort, and shortcut guarding to reduce accidental cross-window effects and disruptive global hotkeys during automation.
• Tool gating: Policy defers the computer-use lane unless the task signals native desktop GUI intent, so gateway and general tasks default to safer tool lanes.
• Key chord blocklist: Certain OS-level shortcuts are rejected at the tool layer to avoid session or system disruption.

Full operator and troubleshooting guidance: Computer use.

Monotonic Policy Precedence (Deny-Wins)

Security policies are evaluated across multiple layers in order:

1. Global Guardrails - Blocked commands, patterns
2. Workspace Permissions - Read, write, delete, shell, network flags
3. Context Restrictions - Gateway context (private/group/public)
4. Tool-Specific Rules - Per-tool overrides

Key invariant: Once denied by any layer, a tool cannot be re-enabled by later layers. This prevents policy bypasses.

Context-Aware Tool Isolation

When tasks originate from gateway bots (WhatsApp/Telegram/Discord/Slack/iMessage/Signal), tools are restricted based on context:

This prevents accidental exposure of sensitive data in shared contexts.

Concurrent Access Safety

Critical operations use mutex locks and idempotency guarantees to prevent race conditions:

Brute-Force Protection

Pairing code verification includes protection against brute-force attacks:

When a user exceeds the maximum attempts:

1. Account is locked for 15 minutes
2. User sees remaining lockout time
3. Attempts counter resets after lockout expires

Implementation: src/electron/gateway/security.ts

Shell Command Sandboxing

On macOS, shell commands execute within a sandbox-exec profile that:

• Restricts filesystem access to workspace + temp directories
• Blocks network access unless workspace has network permission
• Limits write access based on workspace permissions
• Uses minimal, safe environment variables

Implementation: src/electron/agent/sandbox/runner.ts

Imported Capability Security

Imported skills and imported plugin packs now pass through the same install-time security gate before activation.

Rejected inputs (skill IDs):

• ../../../etc/passwd - Path traversal
• foo/bar - Contains path separator
• skill;rm -rf / - Special characters

Rejected inputs (binary names):

• node; rm -rf / - Shell metacharacters
• $(whoami) - Command substitution
• `whoami` - Backtick execution

Imported bundles that cannot be fully checked against network-backed intelligence are allowed to install only when the local scan is otherwise clean, and the UI surfaces that reduced-confidence state as a warning.

Implementation:

• src/electron/agent/skill-registry.ts (skill ID validation)
• src/electron/agent/skill-eligibility.ts (binary name sanitization)
• src/electron/security/capability-bundle-security.ts (bundle scanning, reports, digest verification, and quarantine)
• src/electron/extensions/pack-installer.ts (pack install staging and scan gate)
• src/electron/extensions/loader.ts (discovery-time integrity checks and quarantine enforcement)

Running Security Tests

npm run test                # Full suite (4,932 tests total: 4,854 passed, 78 skipped; includes security)
npx vitest run tests/security   # Security-focused tests only (135 tests)
npm run test:coverage       # With coverage report

Test files:

• tests/security/tool-groups.test.ts - Tool categorization tests
• tests/security/policy-manager.test.ts - Policy evaluation tests
• tests/security/concurrency.test.ts - Mutex and idempotency tests
• tests/security/sandbox-runner.test.ts - Sandbox execution tests
• tests/security/gateway-security.test.ts - Brute-force protection tests

---

Summary

CoWork OS is designed with security in mind:

The security model is transparent and consent-based. You remain in control of what the AI can do on your machine.

Guardrails Settings Location

All guardrail settings can be configured at:

• Database: Stored encrypted in app.getPath('userData')/cowork-os.db (category: guardrails)
• UI: Settings (gear icon) → Guardrails tab

Settings Migration

Legacy JSON settings files are automatically migrated to the encrypted database:

• Migration creates a .migration-backup file before proceeding
• On successful migration, both backup and original are deleted
• On failed migration, backup is preserved for recovery
• Migration logs are available in the app console