Native macOS port#

The initial contribution was tested on Apple Silicon, macOS 26.5.2, with Homebrew Python 3.14.7. The native CI workflow runs shared contracts on Linux, Apple Silicon macOS 15 and Intel macOS 15. Support is limited to the capabilities below; CI does not qualify every Mac or model provider.

Managed Mac node#

Install Homebrew Python 3.12 or later and tmux. Install the helper archive generated by this source's ficc.ssh.archive() under ~/.local/lib/ficc/node.pyz, using the normal helper installer. Verify the SSH host key, approve the Mac's SSH profile, and enroll it from the controller.

The archive bootstrap selects Homebrew Python on macOS when Apple's default Python is too old. It adds Homebrew to the helper's process environment without changing shell startup files. CPU uses Mach counters; memory, boot identity, disk and network use native macOS interfaces. Available memory is the sum of free, inactive and speculative pages, excluding duplicate purgeable counts.

The initial native macOS qualification covered:

• Live CPU, load, memory, disk, uptime and network reporting.
• Ephemeral SSH shells and persistent tmux terminals, including FICC WebSocket transport and explicit stop.
• Installed agent runtime probes and the existing agent protocol. Runtime versions outside the explicitly qualified direct-adapter versions retain inbox delivery. Provider sign-in and trust prompts remain native.
• Codex 0.160.1 native app-server/TUI integration with an actual model turn: direct session inclusion, shell/file tools, inbox list/read, addressed replies, retry deduplication and clean stop. Its background title generation preserves the registered session binding.

Resource-limited managed jobs still require Linux systemd/cgroups. The safe file adapter still requires Linux openat2 and related kernel operations. These capabilities are reported unavailable; the helper does not weaken those checks. Apple Silicon GPU observations use bounded, unprivileged IORegistry queries. Available utilization and used unified memory are shown; total GPU memory and temperature remain unknown. Apple GPUs cannot reserve CUDA jobs. See GPU observations for the recorded hardware checks and limits.

An older controller can use this helper, but its Upgrade helper action would reinstall the older Linux-only archive. Use this port's archive when upgrading Mac nodes until the controller also carries the port. Linux helpers remain compatible with this source.

Mac controller#

Install Homebrew Python 3.12 or later, Node.js 22 or later, coreutils and tmux. From a source checkout, build the frontend and host wheel, then install it in a separate private runtime. For example, with Homebrew Python 3.12:

brew install python@3.12 node@22 coreutils tmux
export PATH="$(brew --prefix node@22)/bin:$PATH"
"$(brew --prefix python@3.12)/bin/python3.12" -m venv .venv-build
.venv-build/bin/python -m pip install --require-hashes -r requirements-build.lock
npm ci --prefix web
npm run build --prefix web
.venv-build/bin/python -m build --wheel --no-isolation
"$(brew --prefix python@3.12)/bin/python3.12" -m venv "$HOME/.local/share/ficc/macos-runtime"
"$HOME/.local/share/ficc/macos-runtime/bin/python" -m pip install --require-hashes -r requirements.lock
"$HOME/.local/share/ficc/macos-runtime/bin/python" -m pip install --no-deps dist/ficc-0.2.6.post4-py3-none-any.whl
"$HOME/.local/share/ficc/macos-runtime/bin/ficc" install-launcher
"$HOME/.local/share/ficc/macos-runtime/bin/ficc" start

This installs the host without Linux executable module bundles. Use a logged-in Mac desktop account for its per-user launchd GUI domain. Provider credentials are configured separately in each agent runtime. Stop an existing controller before updating its private runtime.

~/Applications/FICC Cluster Commander.app opens the authenticated local console. ficc status checks readiness and ficc stop unloads its launchd job. The generated ~/Library/LaunchAgents/ficc.plist starts on demand by default; the server listens only on 127.0.0.1:8170. No global Python install is changed.

The existing install.sh still packages Linux; it is not the Mac installation entry point. Mac controller qualification covers authenticated startup, the local CLI, process supervision and PTYs. Executable modules, Linux native viewer bundles, controller-local file roots, and the Linux-oriented backup/export commands are not qualified on macOS. Keep any manual state copy private and stop the service first. Remote Linux nodes retain their own capabilities.

Local credential checks use getpeereid; child exit monitoring uses kqueue. Children remain unreaped until their owned process groups are cleaned up. Darwin's EPERM response for zombie-only groups is accepted only after checking that no live group members remain.

Shared agent and CI checks#

OMP, Codex and generic profiles use the same host-owned sessions, inbox, tools, terminal attachment and stop/archive workflow on both platforms. Qualified versions add direct delivery; see coding agents for exact versions and fallbacks. Other command-line agents use the generic profile unless an explicit native adapter is documented.

The Native platforms workflow builds and installs the controller wheel on Ubuntu, Apple Silicon macOS and Intel macOS. It checks native peer credentials, child cleanup, helper installation, SSH/tmux transport and the shared agent protocol. Pinned OMP 18.1.12 exercises its real extension and RPC interface with a scripted response stream; pinned Codex 0.160.1 exercises native startup and session binding without requesting model inference. Missing required runtimes fail CI. Mac jobs also start, authenticate, repeat-start and stop an isolated real launchd controller. Linux sandbox, executable module and package checks remain in the Linux workflows.

These tests use native operating-system interfaces. They do not emulate macOS from Linux, require provider credentials, or claim live-model qualification for all supported clients. The separately opted-in model test below retains that additional boundary.

Run the native harness check#

After installing the helper on a trusted test Mac, run from a Linux controller checkout with development dependencies installed:

FICC_MACOS_PROFILE=mac-test PYTHONPATH=src:node \
  python -m pytest -q -s tests/integration/test_macos_harness.py

Set FICC_MACOS_SSH_CONFIG if the test alias lives in a separate SSH config. The test creates an isolated controller and temporary Mac workspace, launches a deterministic fixture agent, checks file/process tools, inbox reads, reply deduplication and terminal attachment, then stops the agent and removes its remote namespaces. It does not contact a model provider.

To qualify an installed, signed-in Codex 0.160.1 with real model calls, opt in explicitly:

FICC_MACOS_PROFILE=mac-test FICC_MACOS_REAL_CODEX=1 PYTHONPATH=src:node \
  python -m pytest -q -s tests/integration/test_macos_codex.py

This uses the runtime's configured model and sign-in. Set FICC_MACOS_CODEX if its executable is outside ~/.local/bin/codex. Before dispatching work, the test permits writes to its temporary workspace, FICC namespace and standard temporary directories for that thread; it preserves the approval policy and does not change global runtime configuration. It submits the operator's tool instructions through the native TUI separately from the bus note, which remains participant testimony. The agent and temporary namespaces are stopped and removed after the check. Recorded successful Codex command executions and their returned JSON establish inbox list/read, both sends and an empty rejection list; a model-written success summary alone cannot pass the test. Unconfirmed termination retains the remote workspace and namespaces for diagnosis.