Install FrontierAgent on macOS

For a detailed Chinese guide and a clone-to-run helper, see macOS 中文安装与运行指南.

Use macOS for the FrontierAgent terminal application and connect it to a hosted or remote OpenAI-compatible model endpoint. macOS cannot run the NVIDIA SGLang images in this repository; an Apple GPU is not an NVIDIA CUDA device.

Install

brew install uv

git clone https://github.com/ApodexAI/FrontierAgent.git
cd FrontierAgent
uv sync --python 3.12 --extra dev
cp .env.example .env

Configure the endpoint in .env:

OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1
OPENAI_MODEL=your-model-name

Then start either workflow:

uv run frontier-agent --native --mode react --cwd /path/to/project
uv run frontier-agent --native --mode agent_team --cwd /path/to/project

--native is explicit here on purpose. On macOS, an invocation with neither --native nor --docker selects the container path whenever a Docker daemon is running — which builds apodex:local from this repository on first use and takes several minutes. Without a daemon it falls back to the native runtime and says so on stderr. Both are supported; which one you get should be your choice rather than a property of whether Docker happens to be running.

Native or Docker on the Mac

Docker Desktop is optional. Where the model runs does not change between these two: both call the hosted endpoint configured above. What changes is where the agent's own commands run.

--native runs them as the current macOS user. Mutable runtime state, dependency caches, temporary files, and inputs are redirected under <project>/.apodex/runtime/native, and approvals remain in effect, but this is a convenience boundary and not an OS sandbox. Note that the redirected HOME means the agent does not see ~/.gitconfig, ~/.ssh or ~/.config/gh; see the note on native mode and your credentials.

Scientific, plotting, spreadsheet, and document-reader packages are not installed by default. When a task needs one, the workflow may install that specific package with python -m pip install <package>; native mode redirects it into the workspace-local Python overlay rather than modifying the CLI venv.

--docker re-executes the whole CLI inside the Linux agent image, and the container is the boundary — the supported way to get a real one on macOS, since macOS has no bubblewrap:

brew install --cask docker
docker info
uv run frontier-agent --docker --mode react --cwd /path/to/project

The first --docker run builds apodex:local from this repository and may take several minutes; later runs reuse the image. The project is mounted at /project, per-session scratch at /workspace, and session deliverables at /outputs, which appears on the host under <project>/.apodex/runs/<session-id>/outputs/. Clones, drafts, and other intermediate files stay under that run's workspace/ instead of spilling into the project root.

APODEX_IMAGE=<tag> selects a different prebuilt image instead. A tag that is not present locally is pulled, never built under that name. For Compose and docker run deployments, see Run FrontierAgent in Docker.

A frontier-agent installed with uv tool install has no repository to build from. Build apodex:local once from a clone, or set APODEX_BUILD_CONTEXT=/path/to/FrontierAgent, before relying on the container path; otherwise the launch stops and lists those options together with --native. Details in Install once and launch from any project.

--bwrap is therefore not available on macOS; it reports that and names these two paths instead.

Docker Desktop does not turn an Apple GPU into a CUDA GPU. To use a local Qwen/SGLang server, run it on a remote Linux NVIDIA machine and set OPENAI_BASE_URL to a securely reachable endpoint.

Return to the installation chooser.