pi-apple-fm

Apple Foundation Models provider for Pi, using macOS 27's built-in fm serve endpoint.

Models appear in Pi's existing /model picker:

• apple-fm/system — on-device Apple Foundation Model
• apple-fm/pcc — Apple Foundation Model on Private Cloud Compute

Requirements

• Apple Silicon Mac
• macOS 27 beta 4 or newer
• Apple Intelligence enabled and model assets downloaded
• Pi

Install

From npm:

pi install npm:pi-apple-fm

From GitHub:

pi install git:github.com/adstastic/pi-apple-fm

From a local checkout:

pi install ./pi-apple-fm

Restart Pi or run /reload.

Use

Ensure Apple's server is running:

/apple-fm

The bare command checks fm serve. If stopped, it opens fm serve in its own Terminal.app tab, bound to 127.0.0.1:1976; if already running, it reports both models' availability. Keep the server tab open. If you close it, the next model request starts a replacement. fm serve must remain the foreground process in that tab—do not append &. Pi itself can run in any terminal and connects over localhost.

Auto-start is enabled by default, so you do not need to run the command before prompting. When an Apple FM model is selected, the package checks server health in Pi's before_provider_request hook. If stopped, it launches Terminal and waits for fm serve to become healthy before sending the model request. The same check runs for post-tool model turns. Disable this behavior with /apple-fm auto-start off.

The on-device system model can use a headless server, but PCC attribution on current macOS 27 betas requires foreground execution inside Terminal.app. This package uses the Terminal path so one server supports both models.

Then open /model and select either model, or launch Pi directly:

pi --provider apple-fm --model system
pi --provider apple-fm --model pcc

Commands

| Command | Behavior | | --- | --- | | /apple-fm | Manually ensure the server is running | | /apple-fm auto-start on | Enable startup before model requests | | /apple-fm auto-start off | Disable startup before model requests | | /apple-fm auto-start status | Show the saved auto-start setting | | /apple-fm status | Check server and model availability without starting anything | | /apple-fm start | Explicitly open fm serve in Terminal.app | | /apple-fm logs | Show recent start/status actions | | /apple-fm help | Show command help inside Pi |

The auto-start preference persists in ~/.pi/agent/pi-apple-fm.json. Startup uses a one-line temporary status and transient completion notice; /apple-fm status shows detailed health on demand. Actions are appended to ~/.pi/agent/logs/pi-apple-fm.log. fm serve inference logs remain visible in its Terminal tab.

Configuration

| Environment variable | Default | Purpose | | --- | --- | --- | | APPLE_FM_PORT | 1976 | Local fm serve TCP port | | APPLE_FM_BIN | /usr/bin/fm | fm executable path |

Limits

• system has roughly 4K context. The package keeps only the current turn, uses a compact system prompt, and exposes only bash; treat it as a stateless shell agent.
• pcc has 32K context and uses a daily account quota. Requests leave the device for Apple's Private Cloud Compute.
• fm serve rejects some valid JSON Schema unions. The package simplifies primitive unions and omits tools with irreducible object unions from Apple FM requests.
• Current integration is text-only. fm image support is not yet exposed by this package.
• fm and its API are macOS 27 beta features and may change between builds.

Server binds only to loopback. Dummy API key is local compatibility metadata; fm serve ignores it.