Security Configuration Guide

This guide covers how to configure security settings in CoWork OS.

Channel Security Modes

Pairing Mode (Recommended)

Pairing mode requires users to enter a code to connect:

1. Go to Settings > Channels > [Your Channel]
2. Set Security Mode to "Pairing"
3. Click Generate Pairing Code
4. Share the 6-character code with the user
5. User sends the code as a message to pair

Configuration:

Security Mode: Pairing
Pairing Code TTL: 300 seconds (default)
Max Pairing Attempts: 5 (default)

Allowlist Mode

Allowlist mode pre-approves specific users:

1. Go to Settings > Channels > [Your Channel]
2. Set Security Mode to "Allowlist"
3. Add user IDs to the Allowed Users list

Finding User IDs:

• Telegram: Use @userinfobot
• Discord: Enable Developer Mode, right-click user
• Slack: User profile > More > Copy member ID

Open Mode (Use Carefully)

Open mode allows anyone to interact:

1. Go to Settings > Channels > [Your Channel]
2. Set Security Mode to "Open"

When to use:

• Private channels only you can access
• Testing environments
• Controlled internal deployments

Context Policies

Per-Context Security

Configure different settings for DMs vs groups:

1. Go to Settings > Channels > [Your Channel] > Context Policies
2. Select the Direct Messages or Group Chats tab
3. Configure:
   • Security mode per context
   • Tool restrictions per context

Recommended Configuration:

Tool Restrictions

Restrict tool groups per context:

Channel Specialization Policy

For shared gateway spaces, channel specialization adds a routing and policy layer on top of context policies:

1. Go to Settings > Channels > [Your Channel] > Channel Specialization
2. Choose a whole-channel default, a specific chat/group, or a topic/thread ID when the channel supports it
3. Select the workspace and agent role for new tasks from that scope
4. Add prompt guidance only when it should apply to every new task from that scope
5. Apply tool restrictions for broad or semi-trusted groups
6. Enable shared context memory only when the participants and workflow are trusted

Specialization tool restrictions merge with context-policy restrictions using deny-first behavior. A channel specialization must not contain provider tokens, bot credentials, or connector secrets.

Workspace Permissions

Basic Permissions

Configure per workspace in Settings > Workspaces. These booleans are coarse capability gates; the permission engine still evaluates explicit rules, guardrails, and mode defaults.

Allowed Paths

Add paths outside workspace that tools can access:

1. Go to Settings > Workspaces > [Your Workspace]
2. Click Add Allowed Path
3. Enter the path (e.g., /Users/me/shared)

Unrestricted Mode

Enable broader file access for development:

1. Go to Settings > Workspaces > [Your Workspace]
2. Toggle Unrestricted File Access

Warning: Only use in trusted environments.

Permission Rules

For explicit tool, domain, path, command-prefix, and MCP-server rules:

1. Open Settings > System & Security
2. Set the default permission mode if needed
3. Add profile rules for global policy
4. Use the workspace-local rule list to review or remove rules for the active workspace

Available rule scopes:

Common mode choices:

• default - safe reads auto-run; writes, deletes, shell, data export, and external effects prompt
• dangerous_only - recommended when you want fewer interruptions without fully disabling review; safe reads/edits and conservative read/test shell commands auto-run, while risky or ambiguous actions still prompt
• dont_ask / bypass_permissions - high-autonomy modes for trusted environments only, but export-sensitive actions still require explicit approval

Workspace-local rules are stored in SQLite and mirrored to .cowork/policy/permissions.json. Removing a workspace rule updates both storage locations when possible.

Export-Sensitive Operations

The permission engine now distinguishes ordinary network reads from outbound data export.

• web_fetch is a normal network read
• http_request stays a normal network read only for simple GET or HEAD requests with no body and no custom headers
• mutating or payload-carrying http_request calls are treated as data_export
• analyze_image and read_pdf_visual are also treated as data_export because file bytes leave the local machine
• parse_document is the local PDF/document text extraction path. Uploaded PDF excerpts and parser output are untrusted document data, but ordinary PDF reading does not leave the local machine unless a later export-capable tool is used.

This means:

• enabling workspace Network does not automatically suppress approval for these export paths
• dont_ask and bypass_permissions still pause on data_export
• the session-level "Approve all" shortcut does not auto-approve export either

Practical examples:

• use a domain allow rule for http_request if a workspace should talk only to api.example.com
• keep web_fetch open to a docs domain while still requiring approval for raw API posts
• expect imports, drag-and-drop files, and channel attachments to show up as untrusted sources in later export prompts

Sandbox Configuration

Sandbox Type

Choose your sandbox implementation:

Docker Configuration

If using Docker sandbox:

Image: node:20-alpine (default)
CPU Limit: 1 core (default)
Memory Limit: 512m (default)
Network Mode: none (default) or bridge

Prerequisites:

• Docker must be installed and running
• User must have permission to create containers

Guardrails

Command Blocking

Built-in blocked patterns:

• sudo - Privilege escalation
• rm -rf / - Destructive deletions
• curl | bash - Remote code execution

Add custom blocked patterns:

1. Go to Settings > Guardrails
2. Add patterns to Custom Blocked Patterns

Trusted Commands

Trusted commands feed the permission engine as compatibility rules:

1. Go to Settings > Guardrails
2. Enable Auto-approve Trusted Commands
3. Default includes: npm/yarn test, git status, ls, etc.

The final decision still comes from the permission engine, so a trusted command can be overridden by an explicit deny rule or a higher-priority hard restriction.

Budget Limits

Set limits per task:

• Max Tokens: Limit API token usage
• Max Cost: Limit spending per task
• Max Iterations: Limit planning loops

Rate Limiting

Rate limits are automatic and not configurable:

Audit Logging

All messages and actions are logged automatically:

• Location: ~/Library/Application Support/cowork-os/
• Database: cowork-os.db
• Tables: audit_log, channel_messages

Verification Checklist

After configuration, verify:

• Pairing mode enabled for external channels
• Context policies configured for groups
• Channel specializations reviewed for shared groups, channels, and threads
• Shared-memory opt-in enabled only for trusted specialized groups
• Workspace permissions appropriate
• Guardrails configured
• Permission rules reviewed
• Sandbox type selected
• Test with a pairing code