swift-apple-intelligence-grpc/README.md

Apple Intelligence gRPC Server

A Swift-based gRPC server that exposes Apple Intelligence (Foundation Models) over the network, allowing any device on your LAN to send prompts and receive streaming AI responses.

Features

• gRPC API - Standard gRPC interface accessible from any language
• Streaming Support - Real-time token streaming for responsive UX
• Menu Bar App - Native macOS app with system tray integration
• Built-in Chat UI - Test the AI directly from the app
• API Key Auth - Optional bearer token authentication
• Auto-Start - Launch at login and auto-start server options

Requirements

• macOS 26+ (Tahoe)
• Apple Silicon Mac (M1/M2/M3/M4)
• Apple Intelligence enabled in System Settings
• Swift 6.0+

Installation

Download Release

Download the latest .dmg from the Releases page, open it, and drag the app to Applications.

Build from Source

# Clone the repository
git clone https://github.com/svrnty/apple-intelligence-grpc.git
cd apple-intelligence-grpc

# Build the menu bar app
swift build -c release --product AppleIntelligenceApp

# Or build the CLI server
swift build -c release --product AppleIntelligenceServer

Usage

Menu Bar App

1. Launch Apple Intelligence Server from Applications
2. Click the brain icon in the menu bar
3. Toggle Start Server to begin accepting connections
4. Use Chat to test the AI directly
5. Configure host, port, and API key in Settings

CLI Server

# Run with defaults (0.0.0.0:50051)
.build/release/AppleIntelligenceServer

# Custom configuration via environment
GRPC_HOST=127.0.0.1 GRPC_PORT=8080 API_KEY=secret .build/release/AppleIntelligenceServer

API

Service Definition

service AppleIntelligence {
  rpc Health(HealthRequest) returns (HealthResponse);
  rpc Complete(CompletionRequest) returns (CompletionResponse);
  rpc StreamComplete(CompletionRequest) returns (stream CompletionChunk);
}

Methods

Method	Type	Description
Health	Unary	Check server and model availability
Complete	Unary	Generate complete response
StreamComplete	Server Streaming	Stream tokens as they're generated

Quick Test with grpcurl

# Health check
grpcurl -plaintext localhost:50051 appleintelligence.AppleIntelligence/Health

# Non-streaming completion
grpcurl -plaintext \
  -d '{"prompt": "What is 2 + 2?"}' \
  localhost:50051 appleintelligence.AppleIntelligence/Complete

# Streaming completion
grpcurl -plaintext \
  -d '{"prompt": "Tell me a short story"}' \
  localhost:50051 appleintelligence.AppleIntelligence/StreamComplete

Configuration

Environment Variable	Default	Description
GRPC_HOST	0.0.0.0	Host to bind (use 0.0.0.0 for LAN access)
GRPC_PORT	50051	Port to listen on
API_KEY	none	Optional API key for authentication

Client Libraries

Connect from any language with gRPC support:

• Python: grpcio, grpcio-tools
• Node.js: @grpc/grpc-js, @grpc/proto-loader
• Go: google.golang.org/grpc
• Swift: grpc-swift
• Rust: tonic

See docs/grpc-client-guide.md for detailed examples.

Project Structure

apple-intelligence-grpc/
├── Package.swift
├── Sources/
│   ├── AppleIntelligenceCore/       # Shared gRPC service code
│   │   ├── Config.swift
│   │   ├── Services/
│   │   │   └── AppleIntelligenceService.swift
│   │   ├── Providers/
│   │   │   └── AppleIntelligenceProvider.swift
│   │   └── Generated/
│   │       └── AppleIntelligence.pb.swift
│   ├── AppleIntelligenceServer/     # CLI executable
│   │   └── main.swift
│   └── AppleIntelligenceApp/        # Menu bar app
│       ├── App.swift
│       ├── ServerManager.swift
│       ├── Models/
│       ├── Views/
│       └── ViewModels/
├── scripts/
│   ├── build-app.sh                 # Build .app bundle
│   └── create-dmg.sh                # Create DMG installer
└── docs/
    ├── grpc-client-guide.md         # Client connection examples
    ├── macos-runner-setup.md        # CI runner setup
    └── pipeline-configuration.md    # CI/CD configuration

CI/CD

Automated builds are configured with Gitea Actions. When a release is created:

1. Builds the app bundle
2. Signs with Developer ID
3. Notarizes with Apple
4. Uploads DMG to release

See docs/pipeline-configuration.md for setup instructions.

Security

• Local Network: By default, the server binds to 0.0.0.0 allowing LAN access
• API Key: Enable authentication by setting the API_KEY environment variable
• Firewall: macOS will prompt to allow incoming connections on first run
• Notarized: Release builds are signed and notarized by Apple

Troubleshooting

Model Not Available

• Ensure Apple Intelligence is enabled: System Settings → Apple Intelligence & Siri
• Requires Apple Silicon Mac with macOS 26+

Connection Refused

• Check the server is running (brain icon should be filled)
• Verify firewall allows connections on the configured port
• Try localhost instead of the IP if testing locally

Authentication Failed

• Include the API key in the Authorization header: Bearer YOUR_API_KEY
• Verify the key matches what's configured in Settings

License

MIT