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 command tools when the active access profile exposes them
• Read and write files
• Browse the web
• Connect to external APIs

All of these capabilities are governed by the active access profile, consent rules, and hard guardrails, and are 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

Access Profiles and Workspace Permissions

Each task has an effective access profile. Choose Ask for approval, Approve for me, Full access, or a validated custom profile from the main composer, or set the default in Settings > System & Security > Permissions. A profile combines sandbox, approval, reviewer, command-tool, filesystem, domain, and network policy. Workspace booleans remain coarse compatibility gates; the permission engine still decides whether a specific action should be allowed, denied, or prompted.

Recommendation: Choose the least-privileged access profile that fits the task. Delete remains separate and should be enabled only where you trust the AI to remove files.

There is no separate shell enable/disable switch for a new task. Older tasks may retain a legacy shell field for compatibility, but a named profile is the authority for modern task command-tool availability. See Access Profiles for custom rules, inheritance, migration, and fail-closed behavior.

Approval System

Approval prompts are now part of a layered permission engine. For a named profile, work inside the granted boundary is ordinary execution: reads, writes, edits, artifact creation, and bounded local commands do not create an approval request. A profile with approval: "never" denies a missing boundary instead of waiting for a prompt.

The local runtime keeps popup approvals disabled by default. An allow decision runs silently; an unresolved ask becomes an assistant message plus a durable inline Deny / Allow once input card. This includes network/on-request access, credential use, data export, MCP and other external side effects, eligible outside-workspace paths, and explicit opt-outs from automatic approval. Set COWORK_APPROVAL_PROMPTS=on before launch only to restore the legacy queue for diagnostics. Hard guardrails still block dangerous commands before any approval path, and exact reasons identify the rule, profile boundary, or guardrail involved. Protected paths, administrator denials, approval: "never", and automated tasks without human input remain fail-closed. Pending approval rows and assistant cards fail closed on restart.

When the legacy queue is enabled, you can approve or deny each request individually and persist some approvals as session, workspace, or profile rules. In the normal runtime, respond to the inline assistant card; it is the only interactive approval surface and grants Allow once.

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

The composer access selector uses the same task-level profile model as the permission engine: Ask for approval, Approve for me, Full access, or a validated custom profile. A profile combines sandbox, approval, reviewer, command-tool, filesystem, and network boundaries. There is no separate shell enable/disable switch. Approval is not a substitute for sandboxing, and a custom profile cannot widen the restrictions inherited from its parent.

Agent Security with Numbat

CoWork can add a Numbat-backed agent-security decision before the ordinary permission and approval layers. The integration is disabled by default and receives a bounded projection of the pending tool call rather than the full task transcript. In Monitor mode it records findings without blocking; in Enforce mode a Numbat denial can block the action, but an allow result cannot grant permission, suppress an approval, or weaken sandbox and network controls.

Configure the runtime under Settings > System & Security > Agent Security or through runtime.agentSecurity in the admin policy. Keep enforcement off until binary provenance, health, and rules have been checked. See Agent Security with Numbat for defaults, failure policy, rule sources, CLI operations, retention, and incident case bundles.

Automation Studio Approvals

Main-sidebar Automation Studio classifies each step as read, local write, external write, or data export. New flows default to confirming external work; data exports always pause in a live run. A step's Skip for safe actions option applies only to read/local work and cannot suppress external-write or export approval.

Before turning on a flow:

1. run a dry test and inspect the previewed destinations and payload shape;
2. review every required Google scope and the selected account;
3. keep connector allowlists narrow when a flow can call MCP tools;
4. use a dedicated signing secret for each webhook receiver and rotate it by turning off affected flows first;
5. verify any interrupted remote action before approving a post-restart retry;
6. remember that stored-payload redaction is key-based defense in depth, not permission to place secrets in ordinary free-text fields.

See Automation Studio for the policy matrix, signed webhook controls, cancellation boundaries, recovery rules, and retention behavior.

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:

| Pattern | Risk | | ------------------------ | --------------------- | ---------------- | | sudo | Elevated privileges | | rm -rf / or rm -rf ~ | Mass deletion | | mkfs | Filesystem formatting | | dd if= | Direct disk writes | | Fork bombs | Process exhaustion | | curl\|bash, wget\|sh | Remote code execution | | chmod 777 | Overly permissive | | > /dev/sd | Direct device writes | | :(){ : | :& };: | Fork bomb syntax |

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 Rules

When a profile contains positive domain rules, built-in browser and network tools are restricted to the specified destinations:

• Exact match: github.com
• Wildcard: *.google.com (matches subdomains, not the apex)
• **.example.com matches the apex and descendants
• Deny rules win over allow rules

Arbitrary subprocess networking is not domain-aware and fails closed when a profile requires domain-level enforcement without a domain-aware proxy.

---

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

Protected paths. Two categories of location are never mutable by tools, even with unrestricted file access or a granted approval:

• OS locations (PROTECTED_FILESYSTEM_ROOTS)
• In-workspace .cowork/policy/** and .git/** (PROTECTED_WORKSPACE_SEGMENTS)

Both are enforced in evaluateWorkspaceFilesystemAccess (src/electron/security/access-profile-paths.ts) and denied with reason protected_path, which is a hard boundary — no approval or rule can satisfy it. The rationale is that the policy files decide whether a tool call is allowed, and git hooks execute on the next commit outside the tool sandbox, so a tool able to write either could rewrite the rules that govern it. Reads are unaffected.

Relatedly, copy_file strips the executable bit from its destination, so copying an executable file cannot be used to create a new one.

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: these project-role rules do not replace the task access profile for process execution. Command tools are subject to the profile's sandbox and filesystem scope, while project-role rules continue to govern the file and workspace-kit surfaces listed above. Review command-tool approvals carefully, especially for tasks using a broad access profile.

Command-tool Execution

When command tools are exposed by the active access profile:

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

run_command first requires the active access profile to expose command tools, then applies guardrails, approval, and the selected access profile. Restricted profiles use the native macOS or Docker sandbox when available; if no OS sandbox is available, execution fails closed. Scoped filesystem rules are canonicalized before execution so symlinks and path traversal cannot escape the approved roots. Domain-scoped network rules are enforced for built-in network tools; arbitrary shell networking is denied when the active sandbox cannot enforce those domains.

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

Internal Addresses Are Blocked for Agent Fetches

Agent-driven network tools (web_fetch, http_request, scraping, browser automation) cannot reach internal targets, checked before any allow rule so an allowlist entry cannot open them:

Loopback is deliberately allowed: the agent legitimately fetches development servers it has just started, and the app's own loopback services all require bearer tokens. A DNS name that resolves to an internal address is also refused — the hostname is resolved before connecting, and re-checked on every redirect hop.

Implementation: src/electron/security/address-classes.ts, applied in evaluateNetworkPolicy and in the fetch tools' redirect loop.

External Link Handling

Links opened from app content go through a single scheme allowlist (src/electron/security/safe-external-url.ts) permitting only http:, https:, and mailto:. This covers the IPC channel, new-window requests, and will-navigate. Schemes such as file:, smb:, or an app-registered protocol are refused, because previewed documents can contain arbitrary hyperlink targets that the document converter does not validate.

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

Control Plane Exposure

The Control Plane binds to loopback by default. Headless/managed deployments fail closed on 0.0.0.0/:: binds unless Tailscale exposure is enabled, the process is running in a privately published container with COWORK_CONTROL_PLANE_BIND_CONTEXT=container, or COWORK_CONTROL_PLANE_ALLOW_INSECURE_PUBLIC_BIND=1 is set as a break-glass override.

Reverse-proxied dashboards should set COWORK_CONTROL_PLANE_ALLOWED_ORIGINS to the public HTTPS origin. Only enable COWORK_CONTROL_PLANE_TRUST_PROXY=1 behind a proxy that controls forwarded headers.

Product Analytics and Outbound Data

CoWork Pulse installation-linked usage reporting is disabled by default and requires explicit opt-in. The independent update check sends version/platform/architecture/surface to pulse.coworkosapp.com without an installation identifier and contributes daily request counts. Model providers, compatible gateways, web search, connectors, channels, and other services also receive operational requests when configured or invoked.

Opted-in Pulse profiles send bounded daily aggregates to a dedicated Cloudflare Worker/D1 database. The server stores an HMAC pseudonym rather than the raw random profile UUID. No prompt, response, file content/name, command, URL, raw task/session ID, or provider/model route is included. Stable pseudonyms make these aggregates longitudinal data, not anonymous data. Operator-configured OTLP telemetry is independent and includes allowlisted event names, timestamps, and hashed correlation IDs. See CoWork Pulse for the exact boundaries, retention, reset/delete semantics, in-flight consent limitations, and production runbook for credentials and backup handling.

Task state and application data are persisted locally by default. Prompts, selected memory snippets, files, credentials, and tool payloads leave the machine only when needed for a provider, gateway, connector, channel, browser target, or other external service that you configure or approve. Each service applies its own retention, privacy, and billing terms.

---

Data Storage

Encrypted Settings Storage (SecureSettingsRepository)

Settings stored through SecureSettingsRepository are encrypted inside the local SQLite database. The SQLite file itself is a normal better-sqlite3 database, not a whole-file SQLCipher database:

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 (app2: records)

• AES-256-GCM encryption
• Key derived via PBKDF2-SHA512 (210,000 iterations) from the per-install machine ID, with a random per-record salt stored alongside the ciphertext
• Fails closed: if no machine identifier can be established, writing secure settings is refused rather than falling back to a key derived from predictable paths
• The stored checksum covers the ciphertext, not the plaintext; plaintext integrity comes from AES-GCM's authentication tag
• Legacy app: records written by earlier versions remain readable and are re-encrypted to the current format on their next successful load, so upgrades migrate in place with no user action

See the Security Hardening Record for what changed and why.

Settings Categories

All these are stored encrypted in the database:

Memory Write Governance

The normal local runtime does not show approval prompts. New memory writes commit immediately, including when an older saved Memory Hub setting selected a review mode. Memory Write Approval remains an explicit compatibility path for controlled runs and can stage durable memory writes before commit. Set COWORK_MEMORY_WRITE_APPROVAL_MODE to opt into it:

• off: writes commit immediately
• curated_only: curated hot-memory edits wait for review
• external_only: Supermemory/external-provider writes wait for review
• background_only: automatic capture, Dreaming, distillation, and external mirroring wait for review
• all: every durable memory write waits for review

Pending rows live in pending_memory_writes inside the normal SQLite database. Since that table is not whole-file encrypted, CoWork blocks sensitive external-memory payloads before queueing them. Approvals first claim rows as applying, then replay the write with the gate bypassed and mark it applied; duplicate or stale approve attempts fail instead of replaying again. To clear a backlog after switching to the no-prompt policy, call MemoryWriteGate.rejectAllPending(): it records a system rejection and never replays the stored payload. The helper only claims rows still marked pending, so an in-flight applying replay is not interrupted. Take a SQLite backup before the one-time cleanup, run it while no replay is active, and verify pendingCount() is zero afterward; do not delete the database to clear this queue.

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, or contacts.

Opt-in location access: get_current_location requests one-time location permission through the operating system's native dialog (macOS Core Location, Windows Location Services, or Linux GeoClue2). Each invocation requires explicit user consent — the permission is never auto-approved or persisted across tasks. Coordinates are not logged; only accuracy and source are recorded in task events.

---

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 from the official repository over HTTPS; the update feed is pinned at build time and cannot be redirected at runtime
3. Downloads are explicit — autoDownload is off
4. Verifies a detached signature before installing, when a release signing key is configured (see below)

Current signing status. Desktop artifacts are not code-signed: macOS builds are packaged ad-hoc and Windows builds carry no publisherName, which makes electron-updater's own signature check inactive. Without the detached-signature scheme enabled, the only integrity control is the sha512 in latest.yml — and that file is published to the same release as the artifact it describes, so it does not protect against someone able to replace release assets.

The detached Ed25519 signature scheme closes this and needs no code-signing certificate, but ships inert until a key is generated. See Release Signing for the current state and how to enable it.

Supply Chain Considerations

Installing MCP Servers

Installing an MCP server whose definition came from the online registry prompts for confirmation first, showing the exact command, arguments, environment variable names, publisher, and transport that will be used. Nothing is spawned before that approval, and the install is refused outright if no confirmation route is available.

This applies to installs triggered from the marketplace UI and to installs requested by the agent (integration_setup), which matters because the agent can be influenced by content it reads. Connectors bundled with the app are not affected and install without a prompt; a remote entry reusing a bundled connector's name is discarded in favour of the bundled one.

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 command-tool calls before approving - read what will execute
2. Use dedicated workspaces - don't point at sensitive directories
3. Choose the least-privileged access profile - only grant 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 Secure MCP Tunnels

1. Require relay admin auth before creating tunnel credentials.
2. Use HTTPS/WSS for non-loopback relays.
3. Prefer explicit tool allowlists over broad access.
4. Enable read-only mode for remote inspection workflows.
5. Rotate caller/client tokens when a device or remote caller is decommissioned.
6. Review audit logs for blocked or unexpected tool calls.

See Secure MCP Tunnels for the tunnel-specific security model.

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 Access Profile And Workspace Permissions

In the app, review the active profile from the composer or Settings > System & Security > Permissions:

• sandbox and approval/reviewer posture
• command-tool availability and network/domain scope
• filesystem roots and read/write/deny rules
• legacy workspace capability gates for older tasks

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 normal runtime has no popup approval queue. Review unresolved decisions in the task timeline's assistant message and inline input card, checking the exact operation, destination, and scope before choosing Allow once. The legacy pending-approval badge and queue are available only when COWORK_APPROVAL_PROMPTS=on is explicitly enabled. Pending rows and assistant approval cards fail closed on restart; retry the operation to receive a fresh decision.

---

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. Access Profile - Sandbox, approval, command-tool, filesystem, and network boundaries
3. Legacy Workspace Permissions - Read, write, delete, and compatibility flags
4. Context Restrictions - Gateway context (private/group/public)
5. 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

Command-Tool Sandboxing

On macOS, profile-enabled command tools execute within a generated sandbox-exec profile; on Linux and Windows, the Docker backend provides the equivalent process boundary when configured. Both backends are fed by the same canonical filesystem evaluator:

• Restricts filesystem access to the active workspace and explicitly approved roots
• Canonicalizes paths and resolves symlinks before allowing reads, writes, or deletes
• Blocks network access unless the active profile and workspace permit it
• Fails closed for arbitrary code with domain-scoped egress that the backend cannot enforce
• Uses a minimal, filtered subprocess environment

Implementation: src/electron/security/access-profile-paths.ts, src/electron/agent/sandbox/macos-sandbox.ts, and src/electron/agent/sandbox/docker-sandbox.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)

Codex Security Scan Containment

The bundled Codex Security pack runs repository, diff, and deep multi-pass security scans through first-party plugin-pack skills. The old security_scan_* built-in helpers are no longer exposed; scan workflows use the normal workspace-scoped task tools plus bundled skill instructions, references, and scripts.

These controls keep the scan workflow auditable and keep scan activity within the same policy boundary as normal CoWork task execution.

Implementation:

• src/electron/agent/tools/registry.ts (normal workspace-scoped tool catalog used by scan skills)
• resources/plugin-packs/codex-security/ (bundled scan skills, references, scripts, and assets)
• src/electron/extensions/loader.ts and src/electron/extensions/registry.ts (directory-backed plugin-pack discovery and skill loading)

See Codex Security Scans for scan modes and artifact contracts.

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 as an encrypted guardrails category inside app.getPath('userData')/cowork-os.db
• UI: Settings (gear icon) → Guardrails tab

Settings Migration

Legacy JSON settings files are automatically migrated into encrypted SecureSettingsRepository categories:

• 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