CoWork-OS

  ██████╗ ██████╗ ██╗    ██╗ ██████╗ ██████╗ ██╗  ██╗      ██████╗ ███████╗
 ██╔════╝██╔═══██╗██║    ██║██╔═══██╗██╔══██╗██║ ██╔╝     ██╔═══██╗██╔════╝
 ██║     ██║   ██║██║ █╗ ██║██║   ██║██████╔╝█████╔╝      ██║   ██║███████╗
 ██║     ██║   ██║██║███╗██║██║   ██║██╔══██╗██╔═██╗      ██║   ██║╚════██║
 ╚██████╗╚██████╔╝╚███╔███╔╝╚██████╔╝██║  ██║██║  ██╗     ╚██████╔╝███████║
  ╚═════╝ ╚═════╝  ╚══╝╚══╝  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝      ╚═════╝ ╚══════╝

The operating system for personal AI assistants

Your AI needs a secure home. CoWork OS provides the runtime, security layers, and I/O channels to run AI agents across WhatsApp, Telegram, Discord, Slack, Microsoft Teams, Google Chat, iMessage, Signal, Mattermost, Matrix, Twitch, LINE, BlueBubbles, and Email — with the control you expect from an operating system.

Status: macOS desktop app (cross-platform support planned)

Security Verified by ZeroLeaks

CoWork OS achieves one of the highest security scores on ZeroLeaks — outperforming solutions like OpenClaw in prompt injection resistance
View Full Security Assessment Report

Terminal-inspired UI with real-time task timeline

Why CoWork OS?

Security Without Compromise

• Configurable guardrails: Token budgets, cost limits, iteration caps
• Dangerous command blocking: Built-in patterns + custom regex rules
• Approval workflows: User consent required for destructive operations
• Pairing & allowlists: Control who can access your AI via messaging channels
• 1800+ tests: Comprehensive test coverage for access control and policies

Your Data, Your Control

• 100% local-first: Database, credentials, and artifacts stay on your machine
• No telemetry: We don't track you
• BYOK: Bring your own API keys — no middleman, no proxy
• Open source: Audit the code yourself

Connect from Anywhere

• Message your AI from WhatsApp, Telegram, Discord, Slack, Microsoft Teams, Google Chat, iMessage, Signal, Mattermost, Matrix, Twitch, LINE, BlueBubbles, or Email
• Mobile Companions: iOS and Android apps for on-the-go access via local network
• Schedule recurring tasks with cron expressions
• Secure remote access via Tailscale or SSH tunnels
• WebSocket API for custom integrations

Developer-Friendly Tools

• Claude Code-style tools: glob, grep, edit_file
• Browser automation with Playwright
• 75+ bundled skills for popular services
• MCP (Model Context Protocol) support for extensibility

Security Architecture

CoWork OS is designed with security as a core principle, not an afterthought.

Defense in Depth

Security Test Coverage

• 132 security unit tests for access control and policy enforcement
• 259 WebSocket protocol tests for API security
• Monotonic policy precedence (deny-wins across security layers)
• Context-aware tool isolation for shared gateway environments

Sandbox Isolation

Shell commands run in isolated sandboxes:

Docker sandbox features:

• CPU and memory limits (--cpus, --memory)
• Network isolation (--network none by default)
• Read-only workspace mounting option
• Automatic cleanup of containers

Per-Context Security Policies

Different security settings for direct messages vs group chats:

Configure per-context policies in Settings > Channels > [Channel] > Context Policies.

See also: docs/security/ for comprehensive security documentation.

Providers & Costs (BYOK)

CoWork OS is free and open source. To run tasks, configure your own model credentials or use local models.

Your usage is billed directly by your provider. CoWork OS does not proxy or resell model access.

Features

Multi-Channel AI Gateway

• WhatsApp: QR code pairing, self-chat mode, markdown support
• Telegram: Bot commands, streaming responses, workspace selection
• Discord: Slash commands, DM support, guild integration
• Slack: Socket Mode, channel mentions, file uploads
• Microsoft Teams: Bot Framework SDK, DM/channel mentions, adaptive cards
• Google Chat: Service account auth, spaces/DMs, threaded conversations, cards
• iMessage: macOS native integration, pairing codes
• Signal: End-to-end encrypted messaging via signal-cli
• Mattermost: WebSocket real-time, REST API, team/channel support
• Matrix: Federated messaging, room-based, end-to-end encryption ready
• Twitch: IRC chat integration, multi-channel, whisper support
• LINE: Messaging API webhooks, reply tokens, 200M+ users in Asia
• BlueBubbles: iMessage via Mac server, SMS support, attachments
• Email: IMAP/SMTP, any email provider, subject filtering, threading

All channels support:

• Security modes (pairing, allowlist, open)
• Brute-force protection
• Session management
• Rate limiting

Agent Capabilities

• Task-Based Workflow: Multi-step execution with plan-execute-observe loops
• Goal Mode: Define success criteria and auto-retry until verification passes
• Dynamic Re-Planning: Agent can revise its plan mid-execution
• 75+ Built-in Skills: GitHub, Slack, Notion, Spotify, Apple Notes, and more
• Document Creation: Excel, Word, PDF, PowerPoint with professional formatting
• Persistent Memory: Cross-session context with privacy-aware observation capture

Voice Mode (NEW)

Talk to your AI assistant with voice input and audio responses.

Supported Providers:

Configure in Settings > Voice.

Persistent Memory System

Capture and recall observations across sessions for improved context continuity.

Privacy Modes:

Configure in Settings > Memory for each workspace.

Configurable Guardrails

Code Tools

Claude Code-style tools for efficient code navigation and editing:

Browser Automation

Full Playwright integration:

• Navigate to URLs, take screenshots, save as PDF
• Click, fill forms, type text, press keys
• Extract page content, links, and form data
• Scroll pages, wait for elements, execute JavaScript

System Tools

• Take screenshots (full screen or specific windows)
• Read/write clipboard content
• Open applications, URLs, and file paths
• Run AppleScript to automate macOS apps
• Get system information and environment variables

Remote Access

• Tailscale Serve: Expose to your private tailnet
• Tailscale Funnel: Public HTTPS endpoint via Tailscale edge
• SSH Tunnels: Standard SSH port forwarding
• WebSocket API: Programmatic task management

MCP (Model Context Protocol)

• MCP Client: Connect to external MCP servers
• MCP Host: Expose CoWork's tools as an MCP server
• MCP Registry: Browse and install servers from a catalog

Personality System

Customize agent behavior via Settings or conversation:

• Personalities: Professional, Friendly, Concise, Creative, Technical, Casual
• Personas: Jarvis, Friday, HAL, Computer, Alfred, Intern, Sensei, Pirate, Noir
• Response Style: Emoji usage, response length, code comments, explanation depth
• Quirks: Catchphrases, sign-offs, analogy domains
• Relationship: Agent remembers your name and tracks interactions

Data Handling

• Stored locally: Task metadata, timeline events, artifact index, workspace config, memories (SQLite)
• Sent to provider: Task prompt and context you choose to include
• Not sent: Your API keys (stored locally via OS keychain), private memories (marked sensitive)

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Security Layers                               │
├─────────────────────────────────────────────────────────────────┤
│  Channel Access Control: Pairing | Allowlist | Rate Limiting     │
│  Guardrails & Limits: Token Budget | Cost Cap | Iterations       │
│  Approval Workflows: Shell | Delete | Bulk Operations            │
│  Workspace Isolation: Path Traversal | File Boundaries           │
└─────────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────────┐
│                    React UI (Renderer)                           │
│  Task List | Timeline | Approval Dialogs | Live Canvas           │
│  Settings | Notification Panel | MCP Registry                    │
└─────────────────────────────────────────────────────────────────┘
                              ↕ IPC
┌─────────────────────────────────────────────────────────────────┐
│                 Agent Daemon (Main Process)                      │
│  Task Queue Manager | Agent Executor | Tool Registry             │
│  Permission Manager | Cron Service | Memory Service              │
└─────────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────────┐
│                    Execution Layer                               │
│  File Operations | Document Skills | Browser Automation          │
│  LLM Providers (6) | Search Providers (4) | MCP Client           │
└─────────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────────┐
│  SQLite Database | MCP Host Server | WebSocket Control Plane     │
│  Tailscale / SSH Tunnel Remote Access                            │
└─────────────────────────────────────────────────────────────────┘

System Requirements

Supported macOS Versions

• macOS 12 Monterey
• macOS 13 Ventura
• macOS 14 Sonoma
• macOS 15 Sequoia

Resource Usage Notes

• Base memory: ~300-500 MB (Electron + React UI)
• Per bot integration: ~50-100 MB additional (WhatsApp, Telegram, etc.)
• Playwright automation: ~200-500 MB when active
• CPU: Mostly idle; spikes during AI API calls (network I/O bound)

Running on a macOS VM

If you prefer not to run CoWork OS on your main Mac, you can install it on a macOS virtual machine:

Recommended VM specs:

• 4+ GB RAM allocated to VM
• 2+ CPU cores
• 40+ GB disk space

This is a good option for:

• Testing before installing on your main machine
• Isolating AI agent file operations from your primary system
• Running experimental tasks in a sandboxed environment

Setup

Prerequisites

• Node.js 18+ and npm
• macOS 12 (Monterey) or later
• One of: Anthropic API key, Google Gemini API key, OpenRouter API key, OpenAI API key, AWS Bedrock access, or Ollama installed locally

Installation

# Clone the repository
git clone https://github.com/CoWork-OS/CoWork-OS.git
cd CoWork-OS

# Install dependencies
npm install

# Run in development mode
npm run dev

# Configure your API credentials in Settings (gear icon)

Building for Production

npm run build
npm run package

The packaged app will be in the release/ directory.

Screenshots

Main interface with task timeline and execution view

Settings panel for AI providers and channel configuration

Messaging channel integrations and security modes

Usage

1. Select a Workspace

On first launch, select a folder where CoWork OS can work. This folder will be:

• Mounted for read/write access
• Protected by permission boundaries
• Used as the working directory for all tasks

2. Create a Task

Click "New Task" and describe what you want to accomplish:

Example Tasks:

• "Organize my Downloads folder by file type"
• "Create a quarterly report spreadsheet with Q1-Q4 data"
• "Generate a presentation about our product roadmap"
• "Analyze these CSV files and create a summary document"

3. Monitor Execution

Watch the task timeline as the agent:

• Creates an execution plan
• Executes steps using available tools
• Requests approvals for destructive operations
• Produces artifacts (files)

Security and workspace configuration options

4. Approve Requests

When the agent needs to perform destructive actions, you'll see an approval dialog. Review the details and approve or deny.

Security & Safety

See also: SECURITY_GUIDE.md for a comprehensive guide on the app's security model, permissions, and best practices.

Important Warnings

• Don't point this at sensitive folders — select only folders you're comfortable giving the agent access to
• Use version control / backups — always have backups of important files before running tasks
• Review approvals carefully — read what the agent wants to do before approving
• Treat web content as untrusted input — be cautious with tasks involving external data

Workspace Boundaries

All file operations are constrained to the selected workspace folder. Path traversal attempts are rejected.

Permission Model

interface WorkspacePermissions {
  read: boolean;      // Read files
  write: boolean;     // Create/modify files
  delete: boolean;    // Delete files (requires approval)
  network: boolean;   // Network access
  shell: boolean;     // Execute shell commands (requires approval)
}

Approval Requirements

The following operations always require user approval:

• File deletion
• Shell command execution (when enabled)
• Bulk rename (>10 files)
• Network access beyond allowlist
• External service calls

Parallel Task Queue

Run multiple tasks concurrently with configurable limits.

How It Works

1. Concurrency Limit: Set maximum simultaneous tasks (1-10, default: 3)
2. FIFO Queue: Tasks beyond the limit are queued in order
3. Auto-Start: Completed tasks trigger the next in queue
4. Persistence: Queued tasks survive app restarts

Queue Panel

When tasks are running or queued, a panel shows:

• Running tasks with spinner indicator
• Queued tasks with position (#1, #2, etc.)
• View and Cancel buttons for each task

Quick Task FAB

Floating action button for rapid task creation:

1. Click the + button
2. Type your task prompt
3. Press Enter to queue

Scheduled Tasks (Cron Jobs)

Schedule recurring tasks with cron expressions and optional channel delivery.

Features

• Cron Expressions: Standard cron syntax (minute, hour, day, month, weekday)
• Workspace Binding: Each job runs in a specific workspace
• Channel Delivery: Send results to Telegram, Discord, Slack, Teams, Google Chat, WhatsApp, iMessage, Signal, Mattermost, Matrix, Twitch, LINE, BlueBubbles, or Email
• Run History: View execution history with status and duration
• Enable/Disable: Toggle jobs without deleting them

Cron Expression Examples

WhatsApp Bot Integration

Run tasks via WhatsApp using the Baileys library for Web WhatsApp connections.

Setting Up WhatsApp

1. Open Settings > WhatsApp tab
2. Click Add WhatsApp Channel
3. Scan the QR code with your phone (WhatsApp > Settings > Linked Devices)
4. Once connected, the channel status shows "Connected"

Self-Chat Mode

Security Modes

Bot Commands

Telegram Bot Integration

Run tasks remotely via Telegram bot.

Setting Up Telegram

1. Create a bot with @BotFather and copy the token
2. Open Settings > Channels tab
3. Enter your bot token and click Add Telegram Channel
4. Test and enable the channel

Bot Commands

Discord Bot Integration

Run tasks via Discord slash commands or direct messages.

Setting Up Discord

1. Create application at Discord Developer Portal
2. Add bot and copy token
3. Enable Message Content Intent in Privileged Gateway Intents
4. Invite bot with bot and applications.commands scopes
5. Configure in Settings > Channels

Slash Commands

Slack Bot Integration

Run tasks via Slack using Socket Mode.

Setting Up Slack

1. Create app at Slack API Apps
2. Enable Socket Mode and create App-Level Token (xapp-...)
3. Add bot scopes: app_mentions:read, chat:write, im:history, im:read, im:write, users:read, files:write
4. Subscribe to events: app_mention, message.im
5. Install to workspace and copy Bot Token (xoxb-...)
6. Configure in Settings > Channels > Slack

Microsoft Teams Bot Integration

Run tasks via Microsoft Teams using the Bot Framework SDK for full bi-directional messaging.

Prerequisites

• Azure account with Bot Services access
• Microsoft Teams workspace where you can add apps
• Public webhook URL (use ngrok for local development)

Setting Up Teams

1. Create an Azure Bot:

   • Go to Azure Portal - Create Bot
   • Choose Multi-tenant or Single-tenant type
   • Create or select a resource group
   • Click Create

2. Get Bot Credentials:

   • In the Bot resource, go to Configuration
   • Copy the Microsoft App ID
   • Click Manage Password to go to App Registration
   • Under Certificates & secrets, create a new client secret
   • Copy the secret value (shown only once)

3. Add Teams Channel:

   • In the Bot resource, go to Channels
   • Click Microsoft Teams and enable the channel

4. Set Up Webhook (for local development):

   ngrok http 3978
   

   • Copy the HTTPS URL from ngrok
   • In Azure Bot Configuration, set Messaging endpoint to: https://your-ngrok-url/api/messages

5. Configure in CoWork OS:

   • Open Settings > Teams tab
   • Enter your Microsoft App ID
   • Enter your App Password (client secret)
   • Optionally enter Tenant ID (for single-tenant apps)
   • Set webhook port (default: 3978)
   • Click Add Teams Bot

Security Modes

Bot Commands

Message Features

• Direct Messages: Chat directly with the bot
• Channel Mentions: @mention the bot in any channel it's added to
• Adaptive Cards: Rich card formatting for responses
• Markdown Support: Basic markdown in messages
• File Attachments: Send documents and images
• Message Editing: Edit and delete messages

Important Notes

• Webhook Required: A public endpoint is needed to receive messages from Teams
• ngrok for Development: Use ngrok or similar to expose local port 3978
• Rate Limits: Teams has rate limits (50 requests/second per bot)
• Auto-Reconnect: Built-in reconnection with exponential backoff

Google Chat Bot Integration

Run tasks via Google Chat using the Google Chat API with service account authentication.

Prerequisites

• Google Cloud project with Chat API enabled
• Service account with appropriate permissions
• Public webhook URL (use ngrok for local development)

Setting Up Google Chat

1. Enable Google Chat API:

   • Go to Google Cloud Console
   • Enable the Google Chat API for your project

2. Create a Service Account:

   • Go to IAM & Admin > Service Accounts
   • Click Create Service Account
   • Give it a name and description
   • Grant roles: Chat Bots Viewer and Chat Bots Admin
   • Create a JSON key and download it

3. Configure Chat App:

   • Go to Chat API Configuration
   • Set App Status to "Live"
   • Under Connection settings, select "HTTP endpoint URL"
   • Enter your public webhook URL (e.g., https://your-ngrok-url/googlechat/webhook)

4. Set Up Webhook (for local development):

   ngrok http 3979
   

   • Copy the HTTPS URL and use it in the Chat API configuration

5. Configure in CoWork OS:

   • Open Settings > Google Chat tab
   • Enter the path to your service account JSON key file
   • Optionally enter Project ID
   • Set webhook port (default: 3979)
   • Click Add Google Chat Bot

Security Modes

Bot Commands

Message Features

• Direct Messages: Chat directly with the bot in 1:1 conversations
• Spaces: Add the bot to Google Chat spaces for team access
• Threaded Replies: Maintains conversation threads
• Cards: Rich card formatting for responses (coming soon)
• Message Editing: Edit and delete messages

Important Notes

• Webhook Required: A public endpoint is needed to receive messages from Google Chat
• ngrok for Development: Use ngrok or similar to expose local port 3979
• Service Account: Different from OAuth - uses JWT for server-to-server auth
• Workspace Users Only: Google Chat bots only work within Google Workspace organizations

iMessage Bot Integration (macOS Only)

Run tasks via iMessage using the imsg CLI tool.

Prerequisites

• macOS with Messages app signed in
• imsg CLI: brew install steipete/tap/imsg
• Full Disk Access granted to Terminal

How It Works

Messages from your own Apple ID are filtered. To use the bot:

• Use a dedicated Apple ID for the bot Mac
• Message the bot from your personal devices

Signal Bot Integration

Run tasks via Signal with end-to-end encryption using signal-cli.

Prerequisites

• signal-cli: Install via Homebrew or from GitHub

  brew install signal-cli
  

• Dedicated phone number: Signal allows only one registration per phone number. Using the bot will deregister your existing Signal app on that number.
• Java Runtime: signal-cli requires Java 17+

Registration Options

Setting Up Signal

1. Register your phone number (if using dedicated number):

   signal-cli -a +1234567890 register
   # Enter verification code when received
   signal-cli -a +1234567890 verify CODE
   

2. Configure in CoWork OS:

   • Open Settings > Signal tab
   • Enter your phone number
   • Select data directory (default: ~/.local/share/signal-cli)
   • Click Add Signal Channel

3. Check registration status using the "Check Registration" button

Security Modes

Trust Modes

Operating Modes

Bot Commands

Important Notes

• Single Registration Limitation: Signal only allows one active registration per phone number. Registering signal-cli will deregister any existing Signal app using that number.
• Verification Codes: You'll need access to receive SMS or voice calls on the phone number for verification.
• Identity Keys: Signal uses identity keys for end-to-end encryption. The trust mode determines how new keys are handled.

Mattermost Bot Integration

Run tasks via Mattermost using the REST API and WebSocket for real-time messaging.

Prerequisites

• Mattermost server (self-hosted or cloud)
• Personal Access Token with appropriate permissions

Setting Up Mattermost

1. Generate a Personal Access Token:

   • Go to Account Settings > Security > Personal Access Tokens
   • Click Create Token and copy the token

2. Configure in CoWork OS:

   • Open Settings > Mattermost tab
   • Enter your server URL (e.g., https://your-team.mattermost.com)
   • Enter your Personal Access Token
   • Optionally specify a Team ID
   • Click Connect Mattermost

Security Modes

Bot Commands

Matrix Bot Integration

Run tasks via Matrix protocol with support for federated messaging and rooms.

Prerequisites

• Matrix homeserver (Matrix.org, Element, Synapse, or self-hosted)
• Access token for your Matrix account

Setting Up Matrix

1. Get your Access Token:

   • Log into your Matrix client (Element, etc.)
   • Go to Settings > Help & About > Advanced
   • Copy your Access Token
   • Or use the Matrix API to generate one

2. Configure in CoWork OS:

   • Open Settings > Matrix tab
   • Enter your homeserver URL (e.g., https://matrix.org)
   • Enter your User ID (e.g., @yourbot:matrix.org)
   • Enter your Access Token
   • Optionally specify Room IDs to monitor
   • Click Connect Matrix

Security Modes

Bot Commands

Important Notes

• Room-Based: Matrix operates on rooms. Configure specific room IDs or let the bot respond in any room it's invited to.
• Federation: Matrix is federated, allowing communication across different homeservers.
• E2EE: End-to-end encryption support depends on room settings.

Twitch Bot Integration

Run tasks via Twitch chat using IRC over WebSocket.

Prerequisites

• Twitch account for the bot
• OAuth token with chat permissions

Getting an OAuth Token

1. Visit twitchtokengenerator.com
2. Select Chat Bot token type
3. Authorize with your Twitch account
4. Copy the OAuth token (starts with oauth:)

Setting Up Twitch

1. Configure in CoWork OS:
   • Open Settings > Twitch tab
   • Enter your Twitch username
   • Enter your OAuth token
   • Enter channel names to join (comma-separated, without #)
   • Optionally enable whispers (DMs)
   • Click Connect Twitch

Security Modes

Bot Commands

Limitations

• No File Attachments: Twitch chat is text-only
• Rate Limited: 20 messages per 30 seconds
• Message Length: 500 characters max per message (auto-split for longer responses)
• Whispers: May require verified account status

LINE Bot Integration

Run tasks via LINE Messaging API with webhooks and push/reply messages.

Prerequisites

• LINE Developers account (developers.line.biz)
• Messaging API channel with Channel Access Token and Channel Secret
• Public webhook URL (use ngrok or cloudflare tunnel for development)

Setting Up LINE

1. Create a LINE Messaging API Channel:

   • Go to LINE Developers Console
   • Create a new provider or select existing
   • Create a new Messaging API channel
   • Copy the Channel Access Token (long-lived)
   • Copy the Channel Secret

2. Configure in CoWork OS:

   • Open Settings > LINE tab
   • Enter your Channel Access Token
   • Enter your Channel Secret
   • Configure webhook port (default: 3100)
   • Click Connect LINE

3. Configure Webhook in LINE Console:

   • Set webhook URL to your public endpoint (e.g., https://your-domain.com/line/webhook)
   • Enable "Use webhook"
   • Disable "Auto-reply messages" and "Greeting messages"

Security Modes

Bot Commands

Message Types

• Reply Messages: Free, use reply tokens (valid 1 minute)
• Push Messages: Uses monthly quota, for proactive messaging

Important Notes

• Reply tokens are ephemeral - valid only for ~1 minute after receiving a message
• Push messages count against quota - free plan has limited monthly messages
• Media messages require hosting URLs (image/video sending not fully implemented)

BlueBubbles Bot Integration

Run tasks via iMessage using BlueBubbles server running on a Mac.

Prerequisites

• Mac computer running 24/7 with Messages app signed in
• BlueBubbles server installed (bluebubbles.app)
• Network access to the BlueBubbles server

Setting Up BlueBubbles

1. Install BlueBubbles Server on Mac:

   • Download from bluebubbles.app
   • Follow setup wizard to configure
   • Note the server URL and password

2. Configure in CoWork OS:

   • Open Settings > BlueBubbles tab
   • Enter your server URL (e.g., http://192.168.1.100:1234)
   • Enter your server password
   • Optionally configure contact allowlist
   • Click Connect BlueBubbles

Security Modes

Bot Commands

Features

• iMessage and SMS: Send to both iMessage and SMS contacts
• Group Chats: Support for group conversations
• Webhooks or Polling: Real-time via webhooks or fallback polling

Important Notes

• Requires Mac running 24/7 - BlueBubbles server must stay online
• iMessage limitations - No message editing or deletion (iMessage doesn't support it)
• Network access - CoWork OS must be able to reach the BlueBubbles server

Email Bot Integration

Run tasks via email using IMAP/SMTP. Universal channel that works with any email provider.

Prerequisites

• Email account with IMAP and SMTP access
• App password (for Gmail, Outlook, Yahoo with 2FA enabled)

Setting Up Email

1. Configure in CoWork OS:
   • Open Settings > Email tab
   • Use quick setup for Gmail, Outlook, or Yahoo (fills server details)
   • Enter your email address
   • Enter your password or app password
   • Configure IMAP and SMTP settings if using other provider
   • Click Connect Email

Email Provider Settings

Security Modes

Bot Commands

Filtering Options

• Allowed Senders: Comma-separated email addresses to accept (leave empty for all)
• Subject Filter: Only process emails containing this text in subject (e.g., [CoWork])

Features

• Reply Threading: Maintains conversation threads via In-Reply-To headers
• Subject Filtering: Only process emails with specific subject patterns
• Sender Allowlist: Restrict to specific email addresses
• Universal: Works with any email provider supporting IMAP/SMTP

Important Notes

• App Passwords: Gmail/Outlook with 2FA require app passwords, not regular passwords
• No editing/deletion: Email doesn't support modifying sent messages
• Attachments: Not yet implemented
• Polling: Uses IMAP polling (default 30 seconds) - not instant delivery

Menu Bar App (macOS)

Native menu bar companion for quick access without the main window.

Features

• Quick access to workspaces and tasks
• Channel connection status
• New task shortcut
• Configure in Settings > Menu Bar

Quick Input Window

Press ⌘⇧Space from anywhere to open a floating input window:

• Global shortcut works from any app
• See responses inline
• Copy results to clipboard

Mobile Companions (iOS/Android)

Access CoWork OS from your iPhone, iPad, or Android device via the local network.

Prerequisites

• CoWork OS running on your Mac
• Mobile device on the same local network (WiFi)
• Control Plane enabled with LAN access

Setting Up Mobile Access

1. Enable Control Plane:

   • Open Settings > Control Plane
   • Check Enable Control Plane
   • Check Allow LAN Connections (Mobile Companions)

2. Get Connection Details:

   • Note your Mac's local IP address (shown in Control Plane settings or run ipconfig getifaddr en0)
   • Copy the authentication token (click Show then Copy)

3. Connect from Mobile App:

   • Enter server URL: ws://<your-mac-ip>:18789 (e.g., ws://192.168.1.100:18789)
   • Enter authentication token
   • Tap Connect

Features

Security Considerations

• LAN Only: Mobile companions connect via local network only (not exposed to internet)
• Token Required: Each connection requires the authentication token
• Firewall: Ensure your Mac's firewall allows connections on port 18789
• Same Network: Mobile device must be on the same WiFi network as your Mac

Troubleshooting

Web Search Integration

Multi-provider web search for research tasks.

Supported Providers

Configure in Settings > Web Search.

Code Tools

Claude Code-style tools for developers.

glob - Pattern-Based File Search

"Find all TypeScript test files"
→ glob pattern="**/*.test.ts"

grep - Regex Content Search

"Find all TODO comments"
→ grep pattern="TODO:" glob="*.ts"

edit_file - Surgical Editing

"Rename function getUser to fetchUser"
→ edit_file file_path="src/api.ts" old_string="function getUser" new_string="function fetchUser"

Web Fetch Tools

web_fetch

Fetch and parse web pages with HTML-to-text conversion.

"Get main content from docs"
→ web_fetch url="https://docs.example.com" selector="main"

http_request

Full HTTP client for API calls (curl-like).

"Check API endpoint"
→ http_request url="https://api.example.com/health" method="GET"

Personality & Customization

Tell the agent what you want:

Ollama Integration (Local LLMs)

Run completely offline and free.

Setup

# Install
brew install ollama

# Pull a model
ollama pull llama3.2

# Start server
ollama serve

Recommended Models

Google Gemini Integration

Setup

1. Get API key from Google AI Studio
2. Configure in Settings > Google Gemini

Models

• gemini-2.0-flash (default)
• gemini-2.5-pro (most capable)
• gemini-2.5-flash (fast)

OpenRouter Integration

Access multiple AI providers through one API.

Setup

1. Get API key from OpenRouter
2. Configure in Settings > OpenRouter

Available Models

Claude, GPT-4, Gemini, Llama, Mistral, and more — see openrouter.ai/models

OpenAI / ChatGPT Integration

Option 1: API Key

Standard pay-per-token access to GPT models.

Option 2: ChatGPT OAuth

Sign in with your ChatGPT subscription to use without additional API costs.

Built-in Skills (75+)

MCP (Model Context Protocol)

MCP Client

Connect to external MCP servers for extended capabilities.

MCP Host

Expose CoWork's tools as an MCP server for external clients.

MCP Registry

Browse and install servers from a catalog with one-click installation.

WebSocket Control Plane

Programmatic API for external automation and mobile companion apps.

Features

• Challenge-response token authentication
• Request/response/event protocol
• Rate limiting for auth attempts
• Full task API (create, list, get, cancel)
• Real-time event streaming
• LAN Access: Enable "Allow LAN Connections" for mobile companion support

Connection Modes

Configure in Settings > Control Plane.

Tailscale Integration

Secure remote access without port forwarding.

• Serve Mode: Expose to your private tailnet
• Funnel Mode: Public HTTPS via Tailscale edge network
• Automatic TLS certificates

SSH Tunnel Support

Standard SSH port forwarding for remote access.

• Connect to remote instances
• Auto-reconnection with backoff
• Encrypted transport with keychain storage

Compliance

Users must comply with their model provider's terms:

• Anthropic Commercial Terms
• Anthropic Usage Policy
• AWS Bedrock Third-Party Model Terms

Roadmap

Completed

• Multi-provider LLM support (6 providers)
• Multi-channel messaging (14 channels)
• Configurable guardrails and security
• Browser automation with Playwright
• Code tools (glob, grep, edit_file)
• Document creation (Excel, Word, PDF, PowerPoint)
• MCP support (Client, Host, Registry)
• WebSocket Control Plane with API
• Tailscale and SSH remote access
• Personality system
• 75+ bundled skills
• 1800+ unit tests
• Docker-based sandboxing (cross-platform)
• Per-context security policies (DM vs group)
• Enhanced pairing code UI with countdown
• Persistent memory system with privacy protection
• Mobile Companions with LAN access support
• Voice Mode with ElevenLabs and OpenAI integration

Planned

• VM sandbox using macOS Virtualization.framework
• Network egress controls with proxy
• Cross-platform UI support (Windows, Linux)

Contributing

See CONTRIBUTING.md for guidelines.

Security

See SECURITY.md for vulnerability reporting.

For end-user security guidance, see:

• SECURITY_GUIDE.md - Quick reference
• docs/security/ - Comprehensive security documentation
  • Security Model - Architecture overview
  • Trust Boundaries - Isolation layers
  • Configuration Guide - Setup instructions
  • Best Practices - Recommended settings

License

MIT License. See LICENSE.

Legal

"Cowork" is an Anthropic product name. CoWork OS is an independent open-source project and is not affiliated with, endorsed by, or sponsored by Anthropic. If requested by the rights holder, we will update naming/branding.