macOS App - TurkeyDPI

Overview

TurkeyDPI includes a native macOS app with a menu bar interface. It provides one-click proxy management without touching the command line.

The macOS app is a SwiftUI application that wraps the TurkeyDPI CLI engine. It offers the same functionality with a graphical interface.

Installation

Build the app

Navigate to the app directory and run the build script:

cd TurkeyDPI-App
./build.sh

This compiles the Swift app and bundles the TurkeyDPI engine.

Open the app

Launch the application:

open TurkeyDPI.app

Or drag TurkeyDPI.app to your Applications folder and launch it from there.

Grant permissions

macOS may ask for permissions:

Network: Required for the SOCKS proxy
System Proxy: Required to automatically configure macOS proxy settings

Click “Allow” for both prompts.

Features

The app lives in your menu bar with a simple interface:

Icon states:
- ○ (Empty circle) - No proxies running
- ● (Filled circle) - At least one proxy running
Menu:
- List of configured proxies with status indicators
- Quick Start/Stop buttons
- Open main window
- Quit application

Main Window

The main window provides full proxy management:

Proxy List
Proxy Details
Create Proxy

Sidebar shows all configured proxies:

● Green dot - Proxy running
○ Gray dot - Proxy stopped
◐ Orange dot - Proxy starting/stopping
● Red dot - Error state

Each proxy shows:

Name
Port number (:8844)

Actions:

Click to select
Right-click for context menu
Click + to create new proxy

Click the + button to create a new proxy configuration:Fields:

Name: Human-readable identifier
Address: Listen address (usually 127.0.0.1)
Port: Port number (default 8844)
ISP Preset: Choose from dropdown
Auto-start: Launch on app startup
System proxy: Automatically configure macOS proxy

Creating Your First Proxy

Open create dialog

Click the + button in the sidebar, or press ⌘N.

Configure proxy

Fill in the form:

Name: Discord Proxy
Address: 127.0.0.1
Port: 8844
ISP Preset: Aggressive
☑ Set as system proxy
☐ Start automatically

Create and start

Click Create. The proxy appears in the sidebar.To start it:

Click the proxy in the list
Click Start button
Or right-click → Start

ISP Preset Selector

When creating a proxy, choose from these presets:

Aggressive
Türk Telekom
Vodafone TR
Superonline

Display: AggressiveDescription: All techniques enabledUse when:

You don’t know your ISP
Other presets don’t work
Maximum compatibility needed

Trade-offs:

Adds ~10ms latency
Higher CPU usage

See ISP Presets for technical details.

System Proxy Integration

The app can automatically configure macOS system proxy settings.

How it works

When “Set as system proxy” is enabled:

On Start: The app runs this command internally:

networksetup -setsocksfirewallproxy Wi-Fi 127.0.0.1 8844
networksetup -setsocksfirewallproxystate Wi-Fi on

On Stop: The app disables the proxy:

networksetup -setsocksfirewallproxystate Wi-Fi off

On Quit: All proxies are disabled:

# Runs for all network interfaces
networksetup -setsocksfirewallproxystate Wi-Fi off
networksetup -setsocksfirewallproxystate Ethernet off

Manual configuration

If you prefer manual control, disable “Set as system proxy” and configure manually:

Open Network Preferences

System Preferences → Network

Select your connection

Click Wi-Fi or Ethernet (whichever you’re using)

Configure proxy

Click Advanced → Proxies tabEnable:

☑ SOCKS Proxy

Enter:

SOCKS Proxy Server: 127.0.0.1
Port: 8844 (or your custom port)

Apply

Click OK → Apply

Real-time Logs

The app displays live logs from the TurkeyDPI engine:

Log Types

Info (Blue)

Normal operational messages:

ℹ Starting proxy on 127.0.0.1:8844...
ℹ Proxy started successfully
ℹ System SOCKS proxy enabled

Success (Green)

Successful operations:

✓ Proxy started successfully
✓ Configuration loaded

Warning (Orange)

Non-critical issues:

⚠ Warning: Could not enable system proxy
⚠ High memory usage detected

Error (Red)

Critical errors:

✗ Error: turkeydpi binary not found
✗ Failed to start: Address already in use

Debug (Gray)

Verbose debug information:

🐜 DEBUG: Processing TLS ClientHello
🐜 TRACE: Fragment size: 5 bytes

Log Features

Auto-scroll: Logs automatically scroll to newest entries
Search: Filter logs (future feature)
Export: Copy logs to clipboard
Clear: Right-click → Clear Logs

Managing Multiple Proxies

The app supports multiple proxy configurations simultaneously.

Use Cases

Proxy 1: "TT Proxy"    - Port 8844 - Türk Telekom preset
Proxy 2: "VF Proxy"    - Port 8845 - Vodafone preset
Proxy 3: "Backup"      - Port 8846 - Aggressive preset

Running Multiple Proxies

Create multiple configurations with different ports
Start the ones you need
Configure applications to use different ports

Only one proxy can use the system-wide proxy setting at a time. If multiple proxies have “Set as system proxy” enabled, the last one started will be active.

Keyboard Shortcuts

Shortcut	Action
`⌘N`	Create new proxy
`⌘W`	Close window
`⌘Q`	Quit application
`⌘,`	Preferences (future)
`⌘R`	Refresh logs

Right-click a proxy in the sidebar for quick actions:

Start - Start the proxy (if stopped)
Stop - Stop the proxy (if running)
Clear Logs - Clear log history
Delete - Remove the proxy configuration

Deleting a proxy is permanent and cannot be undone. The proxy will be stopped if running.

Application Lifecycle

Startup

App checks for stale processes from previous crashes
Kills any leftover turkeydpi-engine processes
Loads saved proxy configurations from UserDefaults
Auto-starts proxies with “Start automatically” enabled
Shows main window and menu bar icon

During Use

Proxies run as child processes
Logs are captured in real-time
Status updates every second
System proxy settings are synchronized

Shutdown

User clicks Quit (or ⌘Q)
App stops all running proxies
System proxies are disabled for all interfaces
Proxy configurations are saved to UserDefaults
All child processes are terminated
App exits

If the app crashes, stale processes are automatically cleaned up on next launch.

Troubleshooting

App won’t start

Check for existing processes:
```
pkill -9 -f turkeydpi-engine
```

Verify binary location: The app looks for the binary in these locations:

TurkeyDPI.app/Contents/MacOS/turkeydpi-engine
TurkeyDPI.app/Contents/Resources/turkeydpi-engine
/usr/local/bin/turkeydpi
/opt/homebrew/bin/turkeydpi
~/.cargo/bin/turkeydpi

Rebuild the app:
```
cd TurkeyDPI-App
./build.sh
```

Proxy fails to start

Error: “turkeydpi binary not found” The app can’t find the CLI binary. Make sure you:

Built the app with ./build.sh
Or installed the CLI: cargo install --path cli

Error: “Address already in use” Another process is using the port. Either:

Change the port number in proxy configuration
Stop the other process:
```
lsof -ti:8844 | xargs kill -9
```

Error: “Permission denied” The app needs network permissions. Go to:

System Preferences → Security & Privacy → Firewall → Firewall Options

Ensure TurkeyDPI is allowed.

System proxy not setting

If the proxy doesn’t enable automatically:

Check permissions: The app may need administrator access for networksetup commands.
Disable and re-enable: Uncheck “Set as system proxy”, stop the proxy, then re-enable and start.
Set manually: Disable automatic setting and configure manually in System Preferences.

Logs not showing

If logs are empty:

Check if proxy is running: Green dot should be visible next to proxy name.
Enable verbose mode: Edit the app code to add -v flag (advanced users only).
Check console: Open Console.app and filter for “turkeydpi” to see system logs.

Technical Details

Architecture

┌─────────────────────────────────────┐
│         SwiftUI App                  │
│  ┌─────────────┐  ┌──────────────┐  │
│  │  MenuBar    │  │  Main Window │  │
│  │  Controls   │  │  Management  │  │
│  └──────┬──────┘  └──────┬───────┘  │
│         │                │          │
│         └────────┬───────┘          │
│                  │                  │
│           ┌──────▼──────┐           │
│           │  AppState   │           │
│           │  (Swift)    │           │
│           └──────┬──────┘           │
└──────────────────┼──────────────────┘
                   │ Process management
                   │ Pipe I/O
          ┌────────▼────────┐
          │  turkeydpi CLI  │
          │  (Rust binary)  │
          └────────┬────────┘
                   │
          ┌────────▼────────┐
          │  SOCKS Proxy    │
          │  DPI Bypass     │
          └─────────────────┘

Data Persistence

Proxy configurations are stored in UserDefaults:

// Saved data structure
struct ContainerConfig: Codable {
    var id: UUID
    var name: String
    var listenAddress: String
    var listenPort: Int
    var preset: ISPPreset
    var autoStart: Bool
    var enableSystemProxy: Bool
}

Key: savedContainers Format: JSON array of ContainerConfig objects

Binary Execution

The app spawns the CLI as a child process:

let process = Process()
process.executableURL = URL(fileURLWithPath: binaryPath)
process.arguments = [
    "bypass",
    "-l", "127.0.0.1:8844",
    "--preset", "aggressive"
]

Stdout and stderr are captured via Pipe objects and displayed in real-time.

Next Steps

Basic Usage

Learn about the CLI interface

ISP Presets

Understand preset configurations in detail

Configuration

Advanced configuration options

Get Started

Usage

Technical Details

Command Reference

​Overview

​Installation

​Features

​Menu Bar Interface

​Main Window

​Creating Your First Proxy

​ISP Preset Selector

​System Proxy Integration

​How it works

​Manual configuration

​Real-time Logs

​Log Types

​Log Features

​Managing Multiple Proxies

​Use Cases

​Running Multiple Proxies

​Keyboard Shortcuts

​Context Menu Actions

​Application Lifecycle

​Startup

​During Use

​Shutdown

​Troubleshooting

​App won’t start

​Proxy fails to start

​System proxy not setting

​Logs not showing

​Technical Details

​Architecture

​Data Persistence

​Binary Execution

​Next Steps

Basic Usage

ISP Presets

Configuration

Build docs developers (and LLMs) love

Overview

Installation

Features

Menu Bar Interface

Main Window

Creating Your First Proxy

ISP Preset Selector

System Proxy Integration

How it works

Manual configuration

Real-time Logs

Log Types

Log Features

Managing Multiple Proxies

Use Cases

Running Multiple Proxies

Keyboard Shortcuts

Context Menu Actions

Application Lifecycle

Startup

During Use

Shutdown

Troubleshooting

App won’t start

Proxy fails to start

System proxy not setting

Logs not showing

Technical Details

Architecture

Data Persistence

Binary Execution

Next Steps