---
summary: "SophiaClaw macOS app - installation, configuration, and usage guide"
read_when:
  - Installing the macOS app
  - Configuring macOS-specific features
  - Troubleshooting macOS issues
title: "macOS App Guide"
---

# SophiaClaw macOS App

The SophiaClaw macOS app is a native menu bar companion that provides seamless integration with the SophiaClaw Gateway. It offers a beautiful native interface for chatting with your AI agent, managing settings, and controlling system permissions.

## Features

- **Menu Bar Integration**: Always accessible from the menu bar
- **Native Chat Interface**: Beautiful SwiftUI chat with topic-based organization
- **Voice Wake**: Hands-free activation with voice commands
- **Canvas Support**: Render AI-generated visualizations and A2UI components
- **System Integration**: Native notifications, permissions, and AppleScript support
- **Non-blocking Task Manager**: Long-running tasks continue in the background
- **Chat History Persistence**: Conversations saved across app restarts

## Installation

### Download Pre-built App (Recommended)

```bash
# Download latest release
curl -L https://github.com/sophiaclaw/sophiaclaw/releases/latest/download/SophiaClaw.dmg -o SophiaClaw.dmg

# Mount and install
open SophiaClaw.dmg
drag SophiaClaw.app to Applications
```

### Build from Source

Requirements:

- macOS 14.0+
- Xcode 15.0+
- Node.js 22+ (for CLI)

```bash
# Clone repository
git clone https://github.com/sophiaclaw/sophiaclaw.git
cd sophiaclaw

# Install dependencies
pnpm install

# Build the macOS app
cd apps/macos
swift build

# Or open in Xcode
open SophiaClaw.xcodeproj
```

## Quick Start

1. **Launch the App**: Open SophiaClaw from Applications
2. **Complete Setup**: Follow the onboarding wizard
3. **Grant Permissions**: Allow Notifications, Accessibility, and other requested permissions
4. **Connect to Gateway**: The app will start or connect to a local Gateway automatically
5. **Start Chatting**: Click the menu bar icon and begin your first conversation

## Architecture

The macOS app consists of several key components:

```
┌─────────────────────────────────────────┐
│         SophiaClaw macOS App            │
├─────────────────────────────────────────┤
│  • SwiftUI Interface                    │
│  • Menu Bar Controller                  │
│  • Chat Window                          │
│  • Settings Panel                       │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│         Node Host Service               │
│  • WebSocket Client                     │
│  • XPC Communication                    │
│  • Permission Manager                   │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│           Gateway (Node.js)             │
│  • AI Agent Core                        │
│  • Channel Routing                      │
│  • Memory & Context                     │
└─────────────────────────────────────────┘
```

## Configuration

### Local vs Remote Mode

**Local Mode (Default)**:

- App manages local Gateway via launchd
- Gateway runs on `127.0.0.1:37521`
- Best for single-user setups

**Remote Mode**:

- Connects to Gateway on another machine
- Requires SSH tunnel or Tailscale
- Gateway runs on remote host

Switch modes in: Settings → Gateway → Connection Mode

### Permission Requirements

The app requires these macOS permissions:

| Permission             | Purpose              | Required    |
| ---------------------- | -------------------- | ----------- |
| Notifications          | Message alerts       | Recommended |
| Accessibility          | UI automation        | Optional    |
| Screen Recording       | Screen capture tools | Optional    |
| Microphone             | Voice wake/talk mode | Optional    |
| Automation/AppleScript | System integration   | Optional    |

### Gateway Service Management

The app uses a LaunchAgent for Gateway persistence:

```bash
# View service status
launchctl print gui/$UID/bot.molt.gateway

# Restart service
launchctl kickstart -k gui/$UID/bot.molt.gateway

# Stop service
launchctl bootout gui/$UID/bot.molt.gateway
```

## Features in Detail

### Chat Interface

The chat window supports:

- **Topic-based organization**: Create separate chats for different contexts
- **Message history**: Scroll through past conversations
- **Tool call display**: See what tools the AI is using
- **Streaming responses**: Real-time response display
- **Keyboard shortcuts**:
  - `⌘N`: New topic
  - `⌘W`: Close window
  - `⌘,`: Open settings
  - `Esc`: Clear composer

### Voice Features

**Voice Wake**:

- Say "Hey Sophia" to activate
- Configure wake phrase in Settings
- Requires microphone permission

**Talk Mode**:

- Continuous voice conversation
- Automatic speech-to-text
- Text-to-speech responses

### Canvas & A2UI

The Canvas allows AI agents to render visual content:

```bash
# Navigate to a URL
sophiaclaw nodes invoke --node "Mac Node" \
  --command canvas.navigate \
  --params '{"url":"http://localhost:37521/__sophiaclaw__/canvas/"}'

# Execute JavaScript
sophiaclaw nodes invoke --node "Mac Node" \
  --command canvas.eval \
  --params '{"javaScript":"alert(\"Hello from Canvas!\")"}'

# Take a snapshot
sophiaclaw nodes invoke --node "Mac Node" \
  --command canvas.snapshot \
  --params '{"format":"png"}'
```

### Exec Approvals (system.run)

Control which commands the AI can execute:

- **Deny Mode**: Block all commands (safest)
- **Ask Mode**: Prompt for each command
- **Allowlist Mode**: Only allow specific patterns

Configure in: Settings → Security → Exec Approvals

Example allowlist:

```json
{
  "version": 1,
  "defaults": {
    "security": "ask",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "allowlist": [{ "pattern": "/opt/homebrew/bin/brew" }, { "pattern": "/usr/bin/git" }]
    }
  }
}
```

## Troubleshooting

### Gateway Connection Issues

**Problem**: "Cannot connect to Gateway"

**Solutions**:

1. Check Gateway status:
   ```bash
   sophiaclaw gateway status
   ```
2. Restart Gateway:
   ```bash
   launchctl kickstart -k gui/$UID/bot.molt.gateway
   ```
3. Check logs:
   ```bash
   log show --predicate 'subsystem == "ai.sophiaclaw.mac"' --last 1h
   ```

### Permission Issues

**Problem**: Permissions show as "Not Determined"

**Solution**:

1. Open System Settings → Privacy & Security
2. Find the relevant permission category
3. Enable SophiaClaw
4. Restart the app

### Build Issues

**Problem**: "No such module 'Sparkle'"

**Solution**:

```bash
cd apps/macos
swift package resolve
swift build
```

### Deep Links Not Working

**Problem**: `sophiaclaw://` URLs don't open the app

**Solution**:

1. Ensure app is in /Applications (not just ~/Applications)
2. Run:
   ```bash
   /System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -f /Applications/SophiaClaw.app
   ```

## Development

### Project Structure

```
apps/macos/
├── Sources/
│   ├── SophiaClaw/
│   │   ├── App/
│   │   │   ├── AppState.swift
│   │   │   └── AppDelegate.swift
│   │   ├── Chat/
│   │   │   ├── ChatView.swift
│   │   │   └── MessageView.swift
│   │   ├── Settings/
│   │   │   ├── SettingsView.swift
│   │   │   └── GatewaySettings.swift
│   │   └── Services/
│   │       ├── GatewayService.swift
│   │       └── NodeService.swift
│   └── SophiaClaw-CLI/
│       └── main.swift
└── Tests/
```

### Debug CLI

Test Gateway connectivity without the full app:

```bash
cd apps/macos
swift run sophiaclaw-mac connect --json
swift run sophiaclaw-mac discover --json
```

### Building for Release

```bash
# Build signed app
BUNDLE_ID=ai.sophiaclaw.mac \
APP_VERSION=2026.3.16 \
SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" \
scripts/package-mac-app.sh

# Create DMG
scripts/create-dmg.sh dist/SophiaClaw.app dist/SophiaClaw-2026.3.16.dmg
```

## Related Documentation

- [macOS Companion (Overview)](/platforms/macos)
- [macOS Release Guide](/platforms/mac/release)
- [macOS Permissions](/platforms/mac/permissions)
- [Canvas Documentation](/platforms/mac/canvas)
- [Voice Wake Setup](/platforms/mac/voicewake)
- [Gateway Configuration](/gateway/configuration)
- [Node Capabilities](/nodes)

## Getting Help

- **Documentation**: https://docs.sophiaclaw.ai
- **Discord**: https://discord.gg/sophiaclaw
- **GitHub Issues**: https://github.com/sophiaclaw/sophiaclaw/issues
- **Email**: hello@sophiaclaw.ai

---

**Note**: This documentation is for the native macOS app. For command-line usage, see the [CLI documentation](/cli).