Overview: The Interactive Desktop Architecture
As engineering teams adopt AI-assisted development, a common question arises: Can we run FlightDeck headlessly inside our cloud CI/CD pipelines (such as GitHub Actions, GitLab CI, or CircleCI) to automate entire App Store releases without human intervention?
The short, definitive answer is: No. FlightDeck is intentionally architected as a native macOS desktop application with an embedded Model Context Protocol (MCP) server, designed exclusively for human-in-the-loop developer workstations.
FlightDeck does not ship a standalone Linux CLI binary, a headless cloud daemon, or an automated bypass for mutation approvals. This architectural choice is deliberate: placing unreviewed App Store mutations on autonomous cloud triggers creates severe operational risks, including accidental storefront updates, unintended price changes, and App Store rejections due to unverified metadata.
┌─────────────────────────────────────────────────────────────────────────────┐
│ RECOMMENDED HYBRID CI/CD & FLIGHTDECK TOPOLOGY │
├─────────────────────────────────────────────────────────────────────────────┤
│ [CLOUD CI/CD PIPELINE: GitHub Actions / GitLab CI] │
│ ├── Trigger: Git Tag / Merge to main │
│ ├── Step 1: Run unit & integration test suites │
│ ├── Step 2: Compile & code-sign archive (xcodebuild / flutter build ipa) │
│ └── Step 3: Headless upload to TestFlight (xcodebuild / Fastlane pilot) │
│ │
│ [DEVELOPER WORKSTATION: macOS Developer Machine] │
│ ├── FlightDeck Desktop GUI (Running locally with active login Keychain) │
│ ├── Embedded MCP Server (127.0.0.1:51122 with loopback security) │
│ ├── AI Coding Assistant (Cursor / Claude Code / Windsurf) │
│ │ • Checks build processing status via builds_list │
│ │ • Analyzes release readiness via release_readiness_check │
│ │ • Stages localized metadata updates & release notes │
│ └── Desktop Approval Center (Human inspects visual diff & clicks APPROVE) │
└─────────────────────────────────────────────────────────────────────────────┘
This guide explains the runtime constraints of FlightDeck Desktop, clarifies what happens when your Mac sleeps or the application closes, and demonstrates how to build an optimal hybrid workflow that combines automated cloud builds with local FlightDeck release governance.
Architectural Constraints of FlightDeck Desktop
Understanding FlightDeck’s local desktop runtime prevents misconfigurations and unrealistic deployment expectations:
1. macOS-Only Operating System Requirement
FlightDeck is built with Flutter for macOS and integrates deeply with native macOS frameworks:
- Keychain Services: API keys (
.p8) and session credentials are encrypted in the user’s macOS login Keychain (login.keychain-db) usingkSecClassGenericPassword. These APIs are unavailable on Linux or Windows cloud runners. - Process Security: FlightDeck uses native macOS IPC and helper binaries (
keychain_bridge.swift) compiled for Apple Silicon and Intel macOS architectures.
2. Embedded Loopback MCP Transport
The Model Context Protocol server inside FlightDeck is not an independent background service. It is instantiated inside the desktop application process:
- Binding: Binds strictly to
http://127.0.0.1:51122/mcp. - Application Exit: If you quit FlightDeck Desktop (
Cmd+Q), the MCP server terminates immediately. Subsequent requests from Cursor or Claude Code fail withECONNREFUSED. - System Sleep: When your Mac enters sleep mode, the network stack pauses. Incoming MCP requests timeout until the Mac wakes.
- No Remote Exposure: FlightDeck enforces loopback Host validation (
127.0.0.1orlocalhost). Exposing the endpoint over public networks or reverse proxies violates security invariants.
3. The Desktop Approval Center Dependency
FlightDeck’s core safety guarantee is that mutating operations (such as creating versions, modifying storefront copy, or submitting for review) must be authorized by a human in the Desktop Approval Center. Because headless cloud runners lack a physical display, an interactive human operator, and a mouse to click "Approve", running FlightDeck headlessly in CI would either cause automated builds to freeze waiting for approval, or require bypassing approvals—violating the tool’s primary reason for existence.
The Hybrid Release Pattern: Cloud Builds + Local Governance
The industry-standard architectural pattern separates artifact compilation from App Store release governance.
| Responsibility | Handled By | Why This Separation Works |
|---|---|---|
| Linting & Unit Tests | GitHub Actions / Cloud CI | Fully deterministic, non-interactive, fast feedback |
| IPA / PKG Compilation | GitHub Actions / Cloud CI | CPU-intensive, reproducible build environments |
| Code Signing | GitHub Actions (Secrets) | Uses distribution certificate & provisioning profile |
| Binary Ingestion | GitHub Actions (xcodebuild / Fastlane) |
Transports heavy binary chunks to Apple servers |
| Build Processing Audit | FlightDeck MCP + AI Agent | Queries Apple processing state conversationally |
| Localized Release Notes | FlightDeck MCP + AI Agent | AI drafts notes from git commits; stages in Approval Center |
| Readiness & ASO Check | FlightDeck MCP + AI Agent | Evaluates 17 preflight readiness gates interactively |
| App Review Submission | FlightDeck Desktop (Human) | Human verifies final visual cards and clicks Submit |
Practical Example: Implementing the Hybrid Workflow
Here is how a real engineering team configures this hybrid workflow in practice.
Step 1: Configure Headless Build in GitHub Actions
In your repository (.github/workflows/deploy.yml), set up a standard workflow to build your iOS application and upload the .ipa to TestFlight using modern Apple tooling (xcodebuild with upload export options, or Fastlane pilot):
name: Build and Upload to TestFlight
on:
push:
tags:
- 'v*.*.*'
jobs:
build:
runs-on: macos-14
steps:
- name: Checkout Code
uses: actions/checkout@v4
- name: Setup Flutter
uses: subosito/flutter-action@v2
with:
channel: 'stable'
- name: Build and Upload IPA
env:
APP_STORE_CONNECT_API_KEY_P8: ${{ secrets.APP_STORE_CONNECT_API_KEY_P8 }}
APP_STORE_CONNECT_KEY_ID: ${{ secrets.APP_STORE_CONNECT_KEY_ID }}
APP_STORE_CONNECT_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }}
run: |
mkdir -p ~/.appstoreconnect/private_keys
echo "$APP_STORE_CONNECT_API_KEY_P8" > ~/.appstoreconnect/private_keys/AuthKey_${APP_STORE_CONNECT_KEY_ID}.p8
# Build release IPA with export options configured for upload
flutter build ipa --release --export-options-plist=ios/ExportOptions.plist
Why Not altool? Apple officially deprecated xcrun altool for notarization and App Store uploads in modern Xcode releases. Modern CI/CD pipelines use xcodebuild -exportArchive with destination: upload configured in ExportOptions.plist, Fastlane pilot, or the App Store Connect API directly.
This workflow handles the heavy lifting: running tests, compiling the native binary, and delivering the raw bytes to Apple.
Step 2: Interactive Release Governance on Your Mac
Once GitHub Actions completes the upload, Apple processes the build on their edge servers (typically 10–30 minutes). Now, switch to your local Mac running FlightDeck Desktop and prompt your AI assistant:
The GitHub Actions build for tag v1.2.0 has finished uploading to Apple.
1. Check the processing state of our latest build using FlightDeck.
2. Once the build is VALID, check whether version 1.2.0 is staged.
3. Review git commits between v1.1.0 and v1.2.0, draft the What's New notes in English and Spanish, and stage the update for my approval.
4. Run a release readiness check and report any blockers.
Do not submit anything to Apple until I approve the changes in FlightDeck Desktop.
Step 3: Human Verification in Desktop Approval Center
- Your AI assistant checks build status via
builds_listand verifies the build state isVALID. - It stages the localized metadata update via
flightdeck_change_set_stage. - In FlightDeck Desktop, you open the Approval Center tab: - You review the English and Spanish release notes. - You verify that the correct build number is attached. - You confirm that export compliance has been attested.
- You click Approve.
- FlightDeck executes the update, and your assistant completes the preflight readiness check.
SSH Tunneling & Remote Access Caveats
Some developers wonder whether they can leave FlightDeck Desktop running on an office Mac mini and access its MCP port from a remote laptop over an SSH tunnel:
ssh -N -L 51122:127.0.0.1:51122 developer@office-mac-mini.local
Technical & Security Caveats:
- Loopback Verification: Because the SSH tunnel terminates on the remote machine's loopback interface, requests arrive with
Host: 127.0.0.1:51122, satisfying FlightDeck’s host header check. - Bearer Token Required: The remote client must still present the valid Authorization Bearer token configured on the desktop host.
- The Human Must Still Click "Approve": Even if the AI agent connects through an SSH tunnel from another machine, mutations still stage in the desktop GUI on the office Mac mini. Someone must physically or via Screen Sharing / VNC view the macOS screen and click "Approve" in the Approval Center.
- Sleep Prevention: If the host Mac sleeps, the tunnel drops. You must configure macOS Energy Saver settings or run
caffeinateto keep the host awake during release windows.
Operational Comparison: FlightDeck vs. Headless CI Fastlane
| Capability | Headless Cloud CI (Fastlane / xcodebuild) | Local Desktop (FlightDeck + MCP) |
|---|---|---|
| Unattended Nightly Builds | Excellent (fully automated) | Unsupported (requires GUI session) |
| Compilation & Archive Export | Native command-line execution | Relies on local CLI or cloud artifacts |
| Conversational AI Control | Difficult / Rigid DSL scripting | Native (prompt any LLM via MCP) |
| Visual Pre-Submission Review | Static CI terminal logs | Native macOS interactive Approval Center |
| Credential Storage | Cloud secrets (GitHub / AWS) | macOS Keychain (kSecClassGenericPassword) |
| Accidental Mutation Risk | High if CI scripts contain logic bugs | Near Zero (guarded by human review) |
Frequently Asked Questions
Can I run FlightDeck as a macOS launchd daemon?
No. FlightDeck is a Flutter GUI application that requires a WindowServer session and accessibility to the login Keychain. Running it as an unattended launchd daemon without an active user GUI login session is unsupported.
Does FlightDeck plan to release a headless CLI server?
FlightDeck’s design philosophy is centered around human-in-the-loop safety for production App Store operations. While read-only headless diagnostics may be explored in future roadmap phases, mutating operations will always prioritize human oversight over fully unattended automation.
Can multiple developers share a single FlightDeck instance?
No. FlightDeck is a single-tenant desktop application bound to the local user’s login session, local Keychain, and local loopback interface. Each developer on a team should run their own FlightDeck Desktop instance configured with their personal or team App Store Connect API keys.
Related Documentation & Authoritative References
- FlightDeck Architecture: Local Loopback MCP Server — Deep dive into the loopback networking model.
- Using Fastlane and FlightDeck Together — Pipeline handoffs between Fastlane and FlightDeck.
- Apple Developer: Uploading Tools and Command-Line Delivery — Apple's official guide on modern command-line upload tooling.
- App Store Connect API Overview — Apple's official REST API specification.