Summary: In the OS 27 betas, Apple's Foundation Models framework stopped being "the on-device model API" and became a general LLM API: anything that conforms to the LanguageModel protocol can be passed to LanguageModelSession. That means one Swift code path can talk to the on-device Apple model, Apple's Private Cloud Compute model, Claude, Gemini, a local MLX model, or any chat-completions server. This walkthrough shows the exact packages and one-line swaps for each, and what actually changes when you leave the on-device model.
What changed, in one paragraph
When the framework shipped with OS 26, a session meant Apple's on-device model, full stop. Apple's developer page now describes it as "a native Swift API for integrating any large language model into your app." The mechanism is the LanguageModel protocol (iOS, iPadOS, macOS, tvOS, visionOS and watchOS 27.0+). A provider writes a light type that declares capabilities plus an executor that translates framework types for its backend, and distributes it as a Swift package. Your app code stays the same: create a session with a model, call respond(to:) or streamResponse(to:), and keep your tools, instructions and @Generable types. Apple's own two models, SystemLanguageModel and PrivateCloudComputeLanguageModel, are simply the first two conforming types.
Before you start
- Xcode 27 beta and the OS 27 SDK. Every third-party bridge below requires them; the Claude package also lists watchOS 27 and visionOS 27, while Firebase's initial release supports iOS and macOS only.
- A device that supports Apple Intelligence if you want Apple's models. Third-party server models do not depend on Apple Intelligence, which is one practical reason to add one as a fallback.
- Beta expectations. The Claude package is labeled beta (0.1.x), the Firebase integration is a Preview with no SLA, and Apple's utilities package is at 1.0.0-beta6. Pin versions.
Step 1: Start from the on-device baseline
Write your feature against the plain on-device session first. It costs nothing per call, works offline and has no usage cap, so it is the right place to get prompts, tools and guided generation working:
import FoundationModels
let session = LanguageModelSession()
let response = try await session.respond(to: "Summarize this note in two lines: ...")
print(response.content)
Apple's own guidance on its Private Cloud Compute page is the same order: start on-device, measure with the Evaluations framework, and only move up when the feature needs more reasoning or context. If you already test prompts outside Xcode, the idea carries over from our Promptfoo tutorial: decide what "good enough" means before switching models.
Step 2: Swap in Private Cloud Compute (one line)
The documented swap is literally the initializer argument:
let session = LanguageModelSession(model: PrivateCloudComputeLanguageModel())
What you get, per Apple's comparison table: 32K context instead of 4K, and reasoning levels (.light, .moderate, .deep via ContextOptions) where the on-device model has none. What you give up: offline use, and unlimited calls, because each person gets a daily request limit. Three things to wire in:
- Availability. Switch on
model.availability; handle.deviceNotEligibleand.systemNotReadywith an alternative UI. - Network failure. Apple suggests retrying on the on-device model when the request fails for lack of a connection.
- Quota UI. Use
model.quotaUsageto show "nearing limit" states, and catchquotaLimitReached. Xcode's scheme options can simulate both the approaching and reached states, so you can test this without burning real requests.
Developing with PCC needs a managed entitlement (com.apple.developer.private-cloud-compute) that you request from Apple. Apple's developer page says developers in the App Store Small Business Program with fewer than two million first-time App Store downloads can use the PCC model with no cloud API cost, and notes that expanded access will carry a fee in the future.
A small router that keeps the on-device model as the default looks like this (our sketch, built only from the documented calls above):
func makeSession(needsLongContext: Bool) -> LanguageModelSession {
if needsLongContext, #available(iOS 27.0, macOS 27.0, *) {
let pcc = PrivateCloudComputeLanguageModel()
if case .available = pcc.availability {
return LanguageModelSession(model: pcc)
}
}
return LanguageModelSession() // on-device default
}
Step 3: Add Claude with Anthropic's package
Anthropic publishes ClaudeForFoundationModels on GitHub. Add it with Swift Package Manager (https://github.com/anthropics/ClaudeForFoundationModels.git, from 0.1.0), import it next to FoundationModels, and pass a ClaudeLanguageModel to the session. Its quick start creates the model with a name such as .sonnet5 and an auth: value, then calls session.respond(to:) exactly as before.
Two details worth knowing before you ship:
- Reasoning maps to effort. The framework's
.light,.moderateand.deepbecome Claude effortlow,mediumandhigh; a level a model does not accept is dropped, not rejected. You can pin one withfixedEffort:. - Fallbacks.
fallbacks:accepts up to three models that the API retries in order if the requested model declines a request in a policy area. A response can even switch models midway; the transcript entry records the handover.
The package documents several auth: modes. Usage bills to your Anthropic workspace.
Step 4: Add Gemini through Firebase AI Logic
Google's route is the Firebase Apple SDK (at least version 12.19.0), adding the FirebaseAILogic and FirebaseAppCheck libraries. After the usual Firebase project setup, the model line is:
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
let model = ai.geminiLanguageModel(name: "gemini-3.8-flash")
let session = LanguageModelSession(model: model)
The supported list covers general models (gemini-4-hydrogen, gemini-4-argon, gemini-4-carbon, gemini-3.8-flash, gemini-3.5-flash-lite) and Nano Banana image models; Live API models are not supported. Firebase's guide enforces App Check from the start, including during development. If you are weighing Carbon for the heavy lifting, our Gemini 4 Carbon pricing breakdown covers what it costs per call.
Step 5: Run an open model locally with MLX
The mlx-swift-lm package now ships MLXFoundationModels, a bridge that builds an MLXLanguageModel you pass to LanguageModelSession. The README example loads a Gemma 3 1B 4-bit configuration with #huggingFaceLanguageModel(configuration:capabilities:) and requests a @Generable struct; output is grammar-constrained to the schema through MLXGuidedGeneration. The key difference from server models: you declare capabilities (.guidedGeneration, .vision, .toolCalling, .reasoning), so the framework only uses what you claim the model supports. For the trade-offs of local weights versus an API in general, see Inkling 2 Small: run it locally or via API.
Step 6: Point at any chat-completions server
Apple's open-source foundation-models-utilities package adds ChatCompletionsLanguageModel, which takes a model name and a base URL (its example uses http://localhost:8000/v1). Set supportsGuidedGeneration: false when your server cannot do structured output. This is also how you reach a gateway: put a proxy like the one in our LiteLLM tutorial in front, and a single Swift model type can reach every backend the proxy knows about. The same package adds history-trimming profile modifiers (drop completed tool calls, rolling window, summarize) and a just-in-time Skills type.
Comparison: which model type to pass
| Model type | Runs where | Offline | Context / reasoning | Cost basis | Status (Nov 14) |
|---|---|---|---|---|---|
| SystemLanguageModel | On device | Yes | 4K, no reasoning | No per-call cost, unlimited | Shipping |
| PrivateCloudComputeLanguageModel | Apple PCC | No | 32K, light/moderate/deep | Daily per-person limit; no cloud API cost for eligible Small Business Program devs | OS 27, entitlement required |
| ClaudeLanguageModel | Anthropic API | No | Per model; effort levels | Billed to your Anthropic workspace | Beta 0.1.x |
| geminiLanguageModel (Firebase) | Gemini API | No | Per model; thinking level | Your Firebase project (Developer API can start at no cost) | Preview |
| MLXLanguageModel | On device, open weights | Yes, after download | Capabilities you declare | Device compute only | 27.0 SDK |
| ChatCompletionsLanguageModel | Any compatible server | If server is local | Depends on server | Whoever runs the server | 1.0.0-beta6 |
What really changes when you leave the on-device model
The API stays the same, but behavior does not, and that is where bugs hide:
- Prompt size. A prompt tuned to fit 4K will not break on bigger models, but a prompt written for a 32K or larger model will fail on-device. If you fall back, keep a shorter prompt variant.
- Feature parity is declared, not guaranteed. Each bridge decides what it supports. Guided generation may be off for a local server, and a Claude schema or image needs every model in a fallback chain to support it.
- Reasoning is a hint. The on-device model ignores reasoning levels; Claude maps them to effort and drops unsupported ones.
- Switching mid-conversation. Dynamic Profiles let one session swap model, temperature, reasoning level and tools while sharing the transcript, so you do not need two sessions to escalate a hard question.
- Testing on the Simulator. Some auth paths need real hardware (see the note below), so plan device testing earlier than you would for the on-device model.
Editor's note
Good fit: iOS/macOS developers who already use LanguageModelSession and want a bigger model for a few hard tasks without a second SDK in their feature code. Not a fit yet: anything that must ship on OS 26 or earlier, or needs a stable API this month; every third-party bridge here is beta or preview.
Common errors and fixes we found in the docs:
ClaudeError.attestationUnsupportedon the Simulator: the Claude package's App Attest mode needs a physical device with a Secure Enclave; its README describes a separate mode for Simulator iteration.- Gemini requests rejected during development: Firebase's guide enforces App Check from setup, so configure the App Check debug provider as the guide describes before you test.
.unavailable(.deviceNotEligible)from PCC: the device or region does not support Apple Intelligence; show an alternative UI or route to a third-party model.quotaLimitReached: the person used their daily PCC allowance; it is not a rate limit, so retrying in a few seconds will not help.- Structured output errors from a local server: set
supportsGuidedGeneration: falseonChatCompletionsLanguageModel.
Gotcha: the MLX README example carries @available(iOS 26.0, ...) on the @Generable struct but wraps the session in #available(iOS 27.0, ...). Your types can stay OS 26-compatible; only the model swap needs 27.
FAQ
Do I need to rewrite my existing Foundation Models code?
No. Sessions, tools, instructions and @Generable types carry over. You change the model passed to LanguageModelSession(model:) and add availability, network and quota handling for server models.
Is the Private Cloud Compute model free?
For people using your app, it comes with a daily limit, and they can upgrade iCloud+ for more. For developers, Apple says Small Business Program members under two million first-time downloads pay no cloud API cost, and that expanded access will carry a fee in the future.
Can I use an OpenAI-compatible or self-hosted model?
Yes, through ChatCompletionsLanguageModel in Apple's utilities package, which works with any server that speaks the chat-completions API, including a local one.
Build on-device first, escalate one feature at a time, and let the protocol keep your code path single.
See the official screenshots and our comparison table at the end of this post. Image credits: screenshots of Apple Developer, Firebase documentation and the ClaudeForFoundationModels GitHub README; comparison table by lightmind24.
lightmind24 is an independent review site, not affiliated with Apple, Anthropic or Google.
Last verified: 2026-11-14
Sources:
Apple: Foundation Models framework
Apple docs: LanguageModel protocol
Apple docs: Adding server-side intelligence with Private Cloud Compute
WWDC26: Bring an LLM provider to the Foundation Models framework
GitHub: anthropics/ClaudeForFoundationModels
Firebase: Access the Gemini API through Apple's Foundation Models framework
GitHub: ml-explore/mlx-swift-lm
GitHub: apple/foundation-models-utilities
댓글
댓글 쓰기