Mantle
GitHub Get started
New: Mantle for macOS · v0.1

Agents that load only what you give them.

Mantle is a local-first CLI and native Mac app for creating and running AI agents on Pi. Each agent has its own agent.yaml, skills, packages and sessions. You sign in to model providers once, and every agent shares the login.

Get started Download for Mac

CLI on Linux and macOS, Windows through WSL · Mac app on Apple Silicon · Apache-2.0

~/projects/shop 
$ mantle agent create reviewer --provider anthropic
Created agent "reviewer" (anthropic/claude-opus-4-8)

$ mantle agent show reviewer
reviewer — Review a project and explain concrete
correctness risks.
  Model:        anthropic/claude-opus-4-8
  Credentials:  shared login
  Runtime:      pi@1.0.0
  Permissions:  filesystem read, shell none
  Skills:       none
  Cloud:        not synced from this machine

$ mantle agent run reviewer

Sign in once to the providers Pi supports

  • Anthropic
  • OpenAI
  • Google
  • DeepSeek
  • GitHub Copilot
  • Local models

Mantle for macOS · new

Prefer a window to a terminal? Use the Mac app.

Mantle for macOS is a native app with Python and Node.js built in, so there's nothing else to install. It reads the same ~/.mantle library as the CLI, so your agents and logins are already there.

  • Create and edit agents in forms, or in the full YAML
  • Add skills and packages from each agent's tabs
  • Chat with an agent in a native window, with streaming replies and tool output
  • Search and resume saved sessions
  • Browse, publish and pull agents from Mantle Cloud

Needs a Mac with Apple Silicon and macOS 14 or later. This first build isn't notarized yet, so the first time you open it, allow it in System Settings → Privacy & Security.

Download for Mac Release notes

Version 0.1.0 · Apple Silicon · 83 MB zip

Mantle

reviewer

Review a project and explain concrete correctness risks.

anthropic/claude-opus-4-8 pi 1.0.0 shared login
Permissions
filesystem read, shell none
Project context
AGENTS.md, CLAUDE.md

How it works

Set up once. Every agent after that is one command.

The installer and mantle setup do the integration work, so your first agent runs in minutes.

  1. 1

    Install

    The installer checks every prerequisite at once and prints the fix for anything missing. It needs no sudo.

    ./install.sh
  2. 2

    Sign in once

    Use an API key or a subscription login. Every agent uses the same login, and a token refreshed in one agent works in all of them.

    mantle auth login anthropic
  3. 3

    Create and run

    Run an agent in any project. Mantle loads its resources plus the project's AGENTS.md and CLAUDE.md.

    mantle agent run reviewer

agent.yaml

One file describes the whole agent.

Model, prompt, resources and permissions live in a single portable file. Mantle validates it before it installs anything, and keeps your comments and formatting when commands change it.

  • Provider and model, switched with mantle agent edit NAME --provider
  • Skills from GitHub, Pi packages from npm or Git
  • Pinned versions for repeatable installs
  • Filesystem and shell permissions
  • Secret names only, never their values
agent.yaml 
mantle: "0.1"
agent:
  name: reviewer
  description: Review a project and explain concrete correctness risks.
runtime:
  name: pi
  version: "1.0.0"
model:
  provider: anthropic
  name: claude-opus-4-8
system_prompt: |
  Read the relevant project files before making claims. Explain each
  finding with its location, triggering condition and practical impact.
permissions:
  filesystem: read
  shell: none
secrets: []

Features

Built for people who run more than one agent.

Mantle handles the parts that usually leak between agents: settings, logins, runtimes and resources.

Configuration isolation

A global Pi skill or setting can't change how your agent behaves. Mantle turns off implicit discovery and loads only the selected agent's resources.

One login for every agent

Logins are stored once with owner-only permissions. Each agent links to them, so you never sign in again inside Pi.

Shared runtimes by version

Each agent pins a Pi version. Every version is downloaded once and shared, and mantle runtime list shows which agents use it.

Skills and packages per agent

Add skills and Pi packages to one agent without touching the others. Pin commits and versions so another machine rebuilds the same thing.

Edits that survive updates

If you edited an agent and never pushed it, an update shows the difference and asks first. A backup is kept every time.

A doctor that prints the fix

mantle doctor re-checks prerequisites, logins, agents and Cloud, and gives you a command to fix each problem it finds.

Mantle Cloud · optional

Move an agent to another machine with two commands.

Mantle Cloud is a small registry for agent.yaml that you host yourself. Push from one machine and pull on another. Every changed push becomes a new revision you can inspect.

  • Only the YAML is sent: no logins, .env, sessions or resources
  • mantle cloud diff shows what changes before you update
  • Runs with Docker Compose on a machine you control

The v0.1 registry has no authentication. Run it on a trusted network or behind a reverse proxy that requires sign-in.

Mantle Cloud on GitHub
r3

reviewer

Review a project and explain concrete correctness risks.

pi 1.0.0 1 skill 1 package

On your laptop

mantle cloud push reviewer

On your workstation

mantle cloud pull reviewer

FAQ

Good to know before you install.

Is Mantle a sandbox?

No. Mantle isolates configuration, not the operating system. It controls which skills, packages and settings an agent loads, but tool restrictions can't constrain extension code or malicious instructions. Only install packages you trust.

What is Pi?

Pi is the agent runtime that Mantle runs. Mantle manages Pi versions, provider logins and each agent's resources around it, so you don't configure Pi by hand.

What do I need to install it?

For the CLI: Linux or macOS (Windows through WSL), Node.js 22.20 or later, Git and uv. If Node.js or uv is missing, the installer offers to install it for your user only. The Mac app needs nothing else: Python and Node.js are built in.

Is there a desktop app?

Yes. Mantle for macOS runs on Apple Silicon Macs with macOS 14 or later. It uses the same agents and logins as the CLI, so you can switch between them. Some advanced Pi terminal features still open in Terminal.

Do my agents run in the cloud?

No. Agents always run on your machine. Mantle Cloud stores configuration only, and it's optional.

What does it cost?

Mantle is free software under the Apache-2.0 license. Your model provider bills you for model usage, as it would anywhere else.

Set up your first agent.

Clone the release and run the installer. It checks prerequisites, offers to add Mantle to your PATH, and starts mantle setup.

git clone --branch v0.1.0 https://github.com/farismohammad/mantle.git
cd mantle && ./install.sh
Read the installation guide Or download the Mac app