The Spaceduck desktop app is a Tauri v2 shell that wraps the web UI in a native window. It supports macOS, Linux, and Windows.
What it does
- Runs the gateway as a sidecar process — starts and stops with the app
- Provides a native window with OS integration (menu bar, window management)
- Connects to the gateway over
http://localhost:3000
- System-wide Fn key dictation — press the Globe/Fn key from any app to start voice input (macOS only)
Running the desktop app
This starts both the gateway sidecar and the Tauri window. The web UI loads automatically.
Building for distribution
The built application is output to apps/desktop/src-tauri/target/release/.
Dictation pill
The desktop app adds a floating dictation pill that appears when you press the Fn (Globe) key from any application. This is a macOS-only feature.
How it works
- Press the Fn/Globe key — a transparent floating pill appears above the Dock
- Speak — the pill shows a real-time waveform visualizer
- Release the Fn key — audio is sent to the gateway for transcription
- The transcribed text is pasted into the active application via Cmd+V
The pill is a transparent, always-on-top window with no title bar. It uses a CGEventTap at the HID level to intercept the Fn key before macOS routes it to the emoji picker.
Multi-monitor support
The dictation pill follows the active screen. When you press Fn on a secondary monitor, the pill appears on that screen, centered horizontally with a fixed gap above the Dock.
Speech-to-text
The dictation pill records audio via the Web Audio API and sends it to the gateway’s /api/stt/transcribe endpoint. The gateway supports two STT backends:
| Backend | Setup |
|---|
| Whisper | pip install openai-whisper — must have whisper on PATH |
| AWS Transcribe | Configure AWS credentials in your environment |
macOS permissions
The desktop app requires two macOS permissions for Fn key dictation to work:
| Permission | Where to enable | Why |
|---|
| Accessibility | System Settings > Privacy & Security > Accessibility | Allows the app to observe keyboard events and simulate paste (Cmd+V) |
| Input Monitoring | System Settings > Privacy & Security > Input Monitoring | Required for HID-level event tap to intercept the Fn/Globe key |
Both permissions must be granted to the Spaceduck app (or the terminal running it during development). You will be prompted on first launch, or you can add the app manually in System Settings.
How it connects
The desktop app loads the web UI from the bundled frontend and connects to the gateway sidecar over localhost. The CSP (Content Security Policy) is configured to allow connections to localhost on any port:
- HTTP and WebSocket connections to
localhost
- Font loading from Google Fonts
- Image loading from
data: and blob: URIs
| Platform | Status |
|---|
| macOS | Supported (full features including Fn key dictation) |
| Linux | Supported (web UI, no Fn key dictation) |
| Windows | Supported (web UI, no Fn key dictation) |
