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.

• Agent execution reliability: task execution now emits long-running tool heartbeats, improves recovery behavior, and adds shell-permission preflight prompts when command execution is required.
• Safer shell automation: run_command now supports single-approval bundles for safe command sequences and redacts sensitive output patterns (seed phrases/private keys).
• Canvas + Control Plane expansion: added ACP delegation endpoints plus new canvas checkpoint/list/restore APIs across control-plane, IPC, and tool surfaces.
• Gateway + UX upgrades: channel defaults now support default/allowed agent-role routing, plus renderer improvements for Talk Mode, task activity signaling, and language preferences (en, ja, zh).
• SkillHub registry + docs/mobile additions: static GitHub-backed skill catalog support, bundled registry snapshots, VitePress docs scaffolding, and mobile companion app scaffolds.
• Install simulation safety: you can now disable OS keychain usage in isolated test environments with COWORK_DISABLE_OS_KEYCHAIN=1 to avoid macOS keychain reset prompts.

Status: macOS desktop app + headless/server mode (Linux/VPS). Cross-platform desktop support planned.

• Download the latest build from GitHub Releases
• In Assets, download the newest Apple Silicon DMG (CoWork-OS-<version>-arm64.dmg)
• Open the .dmg and drag CoWork OS into Applications
• Eject the mounted DMG after copying, then launch only /Applications/CoWork OS.app (prevents duplicate app instances/icons)
• This app is currently distributed as an unsigned build. On first launch, use System Settings > Privacy & Security > Open Anyway once.
• Terminal fallback: xattr -dr com.apple.quarantine "/Applications/CoWork OS.app"
• If the app closes immediately with a dyld signature error, run: codesign --force --deep --sign - "/Applications/CoWork OS.app"
• spctl --add / spctl --enable are deprecated on newer macOS and may show "This operation is no longer supported"

Use this flow to test like a first-time user in a clean folder:

# Install into a local folder
mkdir -p /tmp/cowork-run
cd /tmp/cowork-run
npm install --ignore-scripts --omit=optional cowork-os@latest --no-audit --no-fund

# Prepare native runtime (Electron binary + native module cache)
npm run --prefix node_modules/cowork-os setup

# Ensure no previously running CoWork instance is active
pkill -f '/cowork-os' || true

# Start app
./node_modules/.bin/cowork-os

This is the first install path users should try on macOS:

If you run plain npm install cowork-os@latest, macOS can still intermittently kill lifecycle scripts during dependency extraction. Use the flow above with --ignore-scripts --omit=optional and npm run --prefix node_modules/cowork-os setup before first launch.

For strict reproducibility on low-memory machines:

export COWORK_SETUP_JOBS=1
export COWORK_SETUP_NATIVE_OUTER_ATTEMPTS=10
export COWORK_SETUP_NATIVE_SHELL_ATTEMPTS=10
# Optional for fully isolated HOME tests: bypass OS keychain integration
export COWORK_DISABLE_OS_KEYCHAIN=1
npm run --prefix node_modules/cowork-os setup

• If setup is interrupted by SIGKILL, close other memory-heavy apps and rerun:
  • npm run --prefix node_modules/cowork-os setup
• For local package testing, use the same --ignore-scripts flow with the tarball:
  • npm init -y
  • npm install --ignore-scripts /path/to/cowork-os-<version>.tgz
  • npm run --prefix node_modules/cowork-os setup
• If you run with an isolated HOME and see a macOS Keychain Not Found dialog, choose Cancel.
  • Do not use Reset To Defaults in this flow.
  • Prefer setting COWORK_DISABLE_OS_KEYCHAIN=1 for disposable install simulations.
• If you already have a global install, verify with coworkd-node --version and avoid launching without dependency setup on first run.

You can also install globally and launch directly:

npm install -g --ignore-scripts --omit=optional --no-audit --no-fund cowork-os

# Optional: verify installed version
npm list -g cowork-os --depth=0

# Ensure no previously running CoWork instance is active
pkill -f '/cowork-os' || true

cowork-os

If the app opens but shows vUnknown or Error invoking remote method 'app:getVersion', you likely connected to an older already-running instance.

Run:

pkill -f '/cowork-os' || true
cowork-os

• Node.js 22+ and npm
• macOS 12 (Monterey) or later
• One of: any supported LLM provider credentials (API key/token or AWS credentials) or Ollama installed locally
• Xcode Command Line Tools (needed to build better-sqlite3 for Electron): xcode-select --install

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

# Install dependencies and set up native modules (includes automatic macOS retry handling)
npm run setup

# Run in development mode
npm run dev

# Configure your API credentials in Settings (gear icon)

If you see Killed: 9 during npm run setup, macOS terminated a native build due to memory pressure.

npm run setup already retries native setup automatically with backoff. Let it continue until it exits. If it still exits non-zero:

pkill -f '/cowork-os' || true
npm run --prefix node_modules/cowork-os setup

If the shell shows zsh: killed again, this usually means your system killed a child process. Repeat with lower-memory settings:

COWORK_SETUP_JOBS=1 \
COWORK_SETUP_NATIVE_OUTER_ATTEMPTS=12 \
COWORK_SETUP_NATIVE_SHELL_ATTEMPTS=12 \
npm run --prefix node_modules/cowork-os setup

If npm run --prefix node_modules/cowork-os setup is itself killed immediately (before setup logs appear), run the native retry wrapper directly:

(cd node_modules/cowork-os && sh scripts/setup_native_retry.sh)

npm run setup   # if not already done
npm run build
npm run package

The packaged app will be in the release/ directory.

If this is your first VPS install, start here (Node-only, no Docker):

1. On your VPS (SSH terminal), connect and verify Node version:

ssh user@your-vps
node -v
npm -v

cowork-os requires Node >=22.12.0. If you see v20/v21, upgrade first:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node -v

2. Install and start CoWork OS (local install, no sudo needed):

mkdir -p ~/cowork-run
cd ~/cowork-run
npm init -y >/dev/null
npm install cowork-os@latest --no-audit --no-fund

export COWORK_IMPORT_ENV_SETTINGS=1
export OPENAI_API_KEY=your_key_here   # or ANTHROPIC_API_KEY=your_key_here
npx coworkd-node --print-control-plane-token

Keep this terminal open. It runs the server and prints your Control Plane token.

If you see sh: 1: tsc: not found right after npx coworkd-node, you are on an older broken npm publish. Upgrade and retry:

npm install cowork-os@latest --no-audit --no-fund

3. On your local machine (second terminal), create the SSH tunnel:

ssh -N -L 18789:127.0.0.1:18789 user@your-vps

If local port 18789 is busy:

ssh -N -L 28789:127.0.0.1:18789 user@your-vps

4. Open the web UI in your browser:

• http://127.0.0.1:18789/ (or http://127.0.0.1:28789/ if you used 28789)
• Paste the token from step 1
• If you skipped OPENAI_API_KEY/ANTHROPIC_API_KEY, use the LLM Setup panel in this UI to configure provider credentials.

For production/persistent setup and Docker/systemd options, use:

• Guide: docs/vps-linux.md
• Overview: docs/self-hosting.md

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

Switch between Modern (default) and Terminal visual themes with a real-time task timeline

• 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
• 2800+ tests: Comprehensive test coverage for access control and policies

• 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

• 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

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

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

• 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

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

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.

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.

• 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
• Inbound attachment persistence (files saved to .cowork/inbox/attachments/)
• Chat commands: /schedule, /digest, /followups, /brief (see channel docs below)
• Ambient mode: Passively ingest all messages without responding (slash commands still routed); enable per-channel in settings
• Self-message capture: Capture your own outgoing messages as context (captureSelfMessages on WhatsApp, iMessage, BlueBubbles)

Customize the app appearance with visual style and color mode options.

Configure in Settings > Appearance.

• Task-Based Workflow: Multi-step execution with plan-execute-observe loops
• Dynamic Re-Planning: Agent can revise its plan mid-execution
• 85+ 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
• Workspace Kit: .cowork/ project kit + markdown indexing with context injection
• Agentic Tribe: Coordinated multi-agent execution with shared checklists, synchronized runs, and team management UI
• Performance Reviews: Score and review agent-role outcomes, with autonomy-level recommendations
• Voice Calls: Outbound phone calls via ElevenLabs Agents (list agents, list numbers, initiate calls)
• Vision: Analyze workspace images (screenshots, photos, diagrams) via analyze_image tool (OpenAI, Anthropic, or Gemini)
• X Browser Fallback: x_action automatically falls back to browser-mode read/write flows when Bird CLI is blocked (rate limits, auth challenges, access issues)
• Attachment OCR (Optional): Extract image text in local file previews with Tesseract (tesseract binary must be installed and on PATH)
• Image Generation: Create images via generate_image with multi-provider support (Gemini, OpenAI gpt-image-1/1.5/DALL-E, Azure OpenAI) and automatic provider selection
• Visual Annotation: Iterative image refinement with the Visual Annotator — generate, annotate, refine, repeat until approved
• Email IMAP Access: Direct IMAP mailbox access via email_imap_unread — check unread emails without needing Google Workspace
• Workspace Recency: Workspaces ordered by last used time for quick access
• Hook-Triggered Heartbeat Wakeups: Agents can act on hook-based wake events as explicit check-in prompts

Talk to your AI assistant with voice input and audio responses, plus make outbound phone calls.

Supported Providers:

Configure in Settings > Voice.

Capture and recall observations across sessions for improved context continuity.

Privacy Modes:

Configure in Settings > Memory for each workspace.

Initialize and maintain a .cowork/ directory inside each workspace for durable context, project scaffolding, and prompt injection.

Notes:

• Context injection is only enabled for private tasks and can be toggled in Settings > Memory Hub.
• Project access rules are enforced for file/edit/grep tools and for project context injection.

Configure in Settings > Memory Hub.

You can define per-role personality and operating guidelines directly in workspace files.
When a role runs, CoWork loads these first; if missing, it falls back to legacy role metadata.

Expected structure:

Role resolution checks these folder candidates in order:

• <normalized role.name> (keeps folder-safe letters, numbers, _, -, .)
• slugified variant of role name (ASCII-safe fallback)
• <normalized role.displayName> (same normalization)
• slugified variant of displayName
• <normalized role.id>
• slugified variant of id
• default

Only non-empty .cowork/agents/... files are used. If no files are found, CoWork uses existing DB role soul notes.

Tips:

• Start by cloning a profile from an existing role: copy one *.md file to a new role folder.
• Keep templates simple; the first 4k chars per file are injected into prompts.
• Keep sensitive values out of these files; .cowork content is sanitized before use.
• Quick scaffold:
  • mkdir -p .cowork/agents/<role-id> && printf '%s\n' "# SOUL.md" "..." > .cowork/agents/<role-id>/SOUL.md
  • If you are unsure about the folder name, place a default profile at .cowork/agents/default/ and copy it to .../<role-id>/.

Coordinate multiple agents as an Agentic Tribe to solve complex tasks together through shared state, context, and tool-calling loops.

Configure in Mission Control > Teams.

Generate performance reviews for agent roles based on recent task outcomes and apply recommended autonomy levels.

Configure in Mission Control > Reviews.

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

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
• Browser automation supports browser_channel:
  • chromium (default bundled Chromium)
  • chrome (system Google Chrome)
  • brave (system Brave or a path set in BRAVE_PATH)

• 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
• Apple Calendar: Create, update, delete calendar events via apple_calendar_action
• Apple Reminders: Create, complete, update, list reminders via apple_reminders_action

• 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 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

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

• 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)

┌─────────────────────────────────────────────────────────────────┐
│                    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 (20+) | Search Providers (4) | MCP Client          │
└─────────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────────┐
│  SQLite Database | MCP Host Server | WebSocket Control Plane     │
│  Tailscale / SSH Tunnel Remote Access                            │
└─────────────────────────────────────────────────────────────────┘

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

• 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)

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

Main interface with task timeline and execution view

Settings panel for AI providers and channel configuration

Messaging channel integrations and security modes

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

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"

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

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

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

• 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

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

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)
}

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

Run multiple tasks concurrently with configurable limits.

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

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

Floating action button for rapid task creation:

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

Schedule recurring tasks with cron expressions and optional channel delivery.

• 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
• Conditional Delivery: Only post results when non-empty (deliverOnlyIfResult) — useful for monitors that should stay silent on no-ops
• Template Variables: Use {{today}}, {{tomorrow}}, {{week_end}}, {{now}} in job prompts for dynamic date context
• Chat Context Variables: Jobs with channel delivery can use {{chat_messages}}, {{chat_since}}, {{chat_until}}, {{chat_message_count}}, {{chat_truncated}} to inject recent chat history into prompts
• Run History: View execution history with status and duration
• Enable/Disable: Toggle jobs without deleting them

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

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"

Run tasks remotely via Telegram bot.

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

Run tasks via Discord slash commands or direct messages.

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

Run tasks via Slack using Socket Mode.

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

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

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

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

• 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

• 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

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

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

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

• 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

• 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

Run tasks via iMessage using the imsg CLI tool.

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

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

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

• 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+

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

• 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.

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

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

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

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

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

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

• 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.

Run tasks via Twitch chat using IRC over WebSocket.

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

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

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

• 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

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

• 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)

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"

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

• 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)

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

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

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

• 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

• 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

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

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

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

• 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])

• 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

• 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

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

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

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

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

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

• CoWork OS running on your Mac
• Mobile device on the same local network (WiFi)
• Control Plane enabled with LAN 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

• 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

Multi-provider web search for research tasks with automatic retry and fallback.

• Automatic Retry: Transient errors (rate limits, timeouts) trigger automatic retry with exponential backoff
• Provider Fallback: If one provider fails, automatically tries the next configured provider
• Graceful Degradation: Returns helpful error messages instead of failing silently

Configure in Settings > Web Search.

Claude Code-style tools for developers.

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

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

Smart Document Detection: Automatically detects document-heavy workspaces (PDF/DOCX/PPTX) and provides helpful guidance to use read_file instead, since grep only searches text files.

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

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

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

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

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

Configure in Settings > Integrations > Notion. Use notion_action to search, read, and update Notion content. Write actions (create, update, append, delete) require approval.

notion_action({
  action: "search",
  query: "Roadmap"
});

notion_action({
  action: "query_data_source",
  data_source_id: "YOUR_DATA_SOURCE_ID",
  filter: {
    property: "Status",
    select: { equals: "Active" }
  },
  sorts: [
    { property: "Updated", direction: "descending" }
  ],
  page_size: 25
});

notion_action({
  action: "query_data_source",
  data_source_id: "YOUR_DATA_SOURCE_ID",
  start_cursor: "NEXT_CURSOR_FROM_PREVIOUS_RESPONSE",
  page_size: 25
});

notion_action({
  action: "update_block",
  block_id: "BLOCK_ID",
  block_type: "paragraph",
  block: {
    rich_text: [{ text: { content: "Updated text" } }]
  }
});

notion_action({
  action: "delete_block",
  block_id: "BLOCK_ID"
});

Configure in Settings > Integrations > Box. Use box_action to search, read, and manage Box files and folders. Write actions (create, upload, delete) require approval.

box_action({
  action: "search",
  query: "Q4 report",
  type: "file",
  limit: 25
});

box_action({
  action: "upload_file",
  file_path: "reports/summary.pdf",
  parent_id: "0"
});

Configure in Settings > Integrations > OneDrive. Use onedrive_action to search, read, and manage OneDrive files and folders. Write actions (create, upload, delete) require approval.

onedrive_action({
  action: "search",
  query: "Roadmap"
});

onedrive_action({
  action: "upload_file",
  file_path: "reports/summary.pdf"
});

Configure in Settings > Integrations > Google Workspace. Unified access to Gmail, Google Calendar, and Google Drive with shared OAuth authentication.

gmail_action({
  action: "send_email",
  to: "[email protected]",
  subject: "Weekly Report",
  body: "Please find the attached report..."
});

google_calendar_action({
  action: "create_event",
  title: "Team Standup",
  start_time: "2025-02-10T09:00:00",
  end_time: "2025-02-10T09:30:00",
  attendees: ["[email protected]"]
});

google_drive_action({
  action: "list_files",
  page_size: 20
});

Configure in Settings > Integrations > Dropbox. Use dropbox_action to search, read, and manage Dropbox files and folders. Write actions (create, upload, delete) require approval.

dropbox_action({
  action: "list_folder",
  path: "/Reports"
});

dropbox_action({
  action: "upload_file",
  file_path: "reports/summary.pdf",
  path: "/Reports/summary.pdf"
});

Configure in Settings > Integrations > SharePoint. Use sharepoint_action to search sites and manage drive items. Write actions (create, upload, delete) require approval.

sharepoint_action({
  action: "search_sites",
  query: "Marketing"
});

sharepoint_action({
  action: "upload_file",
  file_path: "reports/summary.pdf"
});

Tell the agent what you want:

Run completely offline and free.

# Install
brew install ollama

# Pull a model
ollama pull llama3.2

# Start server
ollama serve

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

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

Access multiple AI providers through one API.

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

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

Standard pay-per-token access to GPT models.

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

Configure these in Settings > LLM Provider by entering API keys/tokens, model IDs, and base URLs when required.

Connect to external MCP servers for extended capabilities.

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

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

Pre-built MCP server connectors for enterprise integrations. Install from Settings > MCP Servers > Browse Registry.

1. Go to Settings > MCP Servers > Browse Registry
2. Find the connector you need (e.g., Salesforce)
3. Click Install
4. Configure credentials when prompted (API keys, OAuth tokens, etc.)
5. The connector tools become available to the agent

Use the connector template to build your own:

cp -r connectors/templates/mcp-connector connectors/my-connector
cd connectors/my-connector
npm install
# Edit src/index.ts to implement your tools
npm run build

See docs/enterprise-connectors.md for the full connector contract and conventions.

Programmatic API for external automation and mobile companion apps.

• 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
• Web Dashboard: Built-in HTML dashboard at http://127.0.0.1:18789/ for headless management (tasks, approvals, workspaces, channels)
• Approval API: List and respond to pending approvals remotely (approval.list, approval.respond)
• Channel Management: Create, update, enable/disable, test, and remove channels via API

Configure in Settings > Control Plane.

Secure remote access without port forwarding.

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

Standard SSH port forwarding for remote access.

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

Users must comply with their model provider's terms:

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

• [x] Multi-provider LLM support (20+ providers including Groq, xAI, Kimi, GitHub Copilot, OpenAI/Anthropic-compatible)
• [x] Multi-channel messaging (14 channels)
• [x] Configurable guardrails and security
• [x] Browser automation with Playwright
• [x] Code tools (glob, grep, edit_file)
• [x] Document creation (Excel, Word, PDF, PowerPoint)
• [x] MCP support (Client, Host, Registry)
• [x] WebSocket Control Plane with API
• [x] Tailscale and SSH remote access
• [x] Personality system
• [x] 85+ bundled skills (code reviewer, PRD, multi-PR review, frontend design, local websearch, developer growth, React Native, Supabase, bird)
• [x] 2800+ unit tests
• [x] Docker-based sandboxing (cross-platform)
• [x] Per-context security policies (DM vs group)
• [x] Enhanced pairing code UI with countdown
• [x] Persistent memory system with privacy protection
• [x] Mobile Companions with LAN access support
• [x] Voice Mode with ElevenLabs and OpenAI integration
• [x] Enterprise MCP Connectors (Salesforce, Jira, HubSpot, Zendesk, ServiceNow, Linear, Asana, Okta)
• [x] Cloud Storage Integrations (Notion, Box, OneDrive, Google Drive, Dropbox, SharePoint)
• [x] Visual Theme System (Modern/Terminal visual styles + Light/Dark/System color modes)
• [x] Workspace recency ordering
• [x] Web search retry with exponential backoff
• [x] Google Workspace Integration (Gmail, Calendar, Drive with shared OAuth)
• [x] Gateway channel cleanup and enhanced security (Matrix direct rooms, Slack groups)
• [x] Agent transient error retry logic for improved reliability
• [x] Smart parameter inference for document creation tools
• [x] Bedrock inference profile auto-resolution (auto-resolves model IDs to inference profiles)
• [x] Gateway hardening (group chat security, streaming coalescing, restart resilience, tool restrictions)
• [x] Outbound phone calls via ElevenLabs Agents (voice_call tool)
• [x] Workspace Kit (.cowork/ init + projects, markdown indexing, context injection, memory hub settings)
• [x] Agentic Tribe (coordinated agentic execution with shared checklists, synchronized runs, and tribe UI)
• [x] Gateway pending selection state for workspace/provider commands (improved WhatsApp/iMessage UX)
• [x] Task result summary persistence from executor to daemon
• [x] Memory retention isolation for sub-agents and public contexts
• [x] Vision tool (analyze_image) for workspace image analysis via OpenAI, Anthropic, or Gemini
• [x] Email IMAP tool (email_imap_unread) for direct mailbox access without Google Workspace
• [x] Chat commands: /schedule, /digest, /followups, /brief across all gateway channels
• [x] Inbound attachment persistence (channel messages save files to .cowork/inbox/attachments/)
• [x] Cron template variables ({{today}}, {{chat_messages}}, etc.) and conditional delivery
• [x] Brave browser channel support via browser_navigate (browser_channel: "chrome" | "chromium" | "brave")
• [x] Image generation via generate_image with multi-provider support (Gemini, OpenAI, Azure OpenAI)
• [x] Visual annotation tools and Agentic Image Loop skill for iterative image refinement
• [x] Inline image preview in task event timeline
• [x] Local memory embeddings and cross-workspace ChatGPT imported memory search
• [x] Apple Calendar and Reminders tools (macOS native via AppleScript)
• [x] Gateway ambient mode (passive message ingestion) and self-message capture
• [x] Use-case skill templates (booking, draft reply, family digest, household capture, newsletter digest, transaction scan)
• [x] Headless Electron mode with env-based credential import (COWORK_IMPORT_ENV_SETTINGS)
• [x] Node.js daemon entrypoint for non-Electron headless deployments (coworkd-node.js)
• [x] Control plane web dashboard, approval API, and channel management API
• [x] Docker and VPS deployment support (Dockerfiles, docker-compose, systemd units)
• [x] Dedicated workspaces for scheduled cron jobs (auto-created from temp workspace)
• [x] Hook wake requests for heartbeat processing, including queueing, coalescing, and immediate scheduling

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

See CONTRIBUTING.md for guidelines.

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

MIT License. See LICENSE.

"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.