Palmier

Website: palmier.me | Web App: app.palmier.me | Android App: caihongxu/palmier-android

You already have AI agents running on your machine. Palmier is an agent-agnostic bridge between those agents and your phone.

From your phone, you can start sessions, schedule tasks, approve requests, and review results. From your machine, your agents can use phone-side capabilities like notifications, location, SMS, contacts, and calendar — so they can react to the real world, not just the terminal.

It runs on your machine as a background daemon and pairs with a mobile-friendly PWA.

What Palmier is

Palmier is an agent-agnostic phone bridge and mobile control layer for the agents you already use.

It is not:

• an agent runtime itself
• a replacement for Claude Code / Codex CLI / Gemini CLI / OpenClaw / Hermes
• a system for driving your phone UI like a human tapping through apps

Instead, Palmier focuses on:

• letting agents access phone-side capabilities and context in the background
• letting you talk to, manage, and schedule your agents from your phone
• making phone integrations work out of the box without requiring users to wire up separate calendar/email/contact stacks

Quick Start

1. Install a supported agent CLI — Claude Code, Gemini CLI, Codex CLI, GitHub Copilot, OpenClaw, or others.

2. Install Palmier:

   Linux / macOS:

   curl -fsSL https://palmier.me/install.sh | bash
   

   Windows (PowerShell):

   irm https://palmier.me/install.ps1 | iex
   

   The one-liner installs Node.js 24+ if needed (via fnm on Linux/macOS, winget on Windows), then palmier globally. If you already have Node.js 24+ and npm:

   npm install -g palmier
   

3. Run the setup wizard from your Palmier root directory (e.g., ~/palmier):

   palmier init
   

   This detects your agents, configures access, installs the background daemon, and starts pairing.

4. Open http://localhost:7256 to access the app locally — no pairing needed.

5. To access from other devices, enter the pairing code shown after init into the PWA.

Prerequisites

• Node.js 24+
• Linux with systemd, macOS 13+, or Windows 10/11
• At least one supported agent CLI

How It Works

Palmier runs as a background daemon (systemd on Linux, launchd on macOS, Task Scheduler on Windows). It invokes your agent CLIs directly, schedules tasks via native OS timers, and exposes an API that the PWA connects to — either directly over HTTP or remotely through a relay server. Agents can interact with the user's mobile device during execution — requesting input, sending push notifications and full-screen alarms, reading SMS/notifications, managing contacts and calendar, and more.

MCP Server

Palmier exposes an MCP server at http://localhost:7256/mcp (streamable HTTP transport). MCP-capable agents can register it to get tool and resource definitions automatically. The same tools and resources are also available as REST endpoints for curl-based agents.

MCP server URL: http://localhost:7256/mcp

Available tools:

Available resources:

Resources support MCP subscriptions — clients can subscribe via resources/subscribe and receive real-time notifications/resources/updated events via the streamable HTTP transport when the resource changes.

All device tools work while the Palmier Android app is in the background — they communicate via FCM data messages which wake the app's service even when it's not in the foreground. Each host has one linked device: the phone the host uses for SMS, contacts, location, and other device capabilities. Choose it at pair time (the "Link the host to this device" checkbox) or later from the drawer. Each capability must be enabled and its Android permission granted via toggles in the linked device's drawer.

Architecture

┌──────────────┐         HTTP          ┌──────────────────┐
│              │◄──────────────────────│                  │
│  Host Daemon │                       │   PWA (Browser)  │
│  (MCP Server)│◄──────┐               │                  │
└──┬────────┬──┘       │               └──────────────────┘
   │        │          │                        │
   ▼        ▼          │  NATS (TLS)            │ NATS (TLS)
┌──────┐ ┌──────┐      │               ┌────────┴─────────┐
│Agent │ │Agent │      └───────────────│  Relay Server    │
│ CLIs │ │Tools/│                       │  (passthrough,   │
│      │ │Rsrcs │◄──── FCM ───────────│   push, FCM)     │
└──────┘ └──────┘                       └──────────────────┘
                                                │
                                           FCM  │
                                                ▼
                                       ┌──────────────────┐
                                       │  Android Device  │
                                       │  (notifications, │
                                       │   SMS, contacts, │
                                       │   calendar, GPS) │
                                       └──────────────────┘
        Local mode (loopback): direct HTTP on the host machine
        Server mode: via relay (events) + auto-LAN direct HTTP for RPC when reachable (native app)

Access Modes

Three ways to reach your host, ordered by setup effort:

Auto-LAN (native app only). When the Android app is on the same network as the host, it transparently routes RPC over direct LAN HTTP (http://<host-ip>:7256/rpc/...) instead of through the relay — lower latency, no protocol change. Browser PWAs can't do this (Private Network Access / mixed-content restrictions) and stay on the relay.

Security & Privacy

Local mode — all traffic stays on 127.0.0.1. No data leaves your machine. The web UI, /pair, and /events reject any non-loopback caller; only /rpc/<method> (bearer-auth) and /health are reachable from the LAN.

Server mode — communication between your device and host is relayed through the Palmier cloud server over TLS-encrypted NATS connections. The server acts as a passthrough relay only — it does not store, log, or inspect any user data, task content, or agent output. The only data the server persists is a host registration ID used for message routing and push subscription tokens for delivering notifications. See the Privacy Policy for full details.

Auto-LAN — direct LAN HTTP requests use the same client token (Bearer auth) generated during pairing. The host validates every /rpc/* call regardless of source.

In all modes, client tokens are generated and validated entirely on your host. The Palmier server never sees or stores them.

Setup Details

Pairing Devices

Local access (http://localhost:7256) works immediately — no pairing needed.

For remote access (web or app), run palmier pair on the host to generate a code, then enter it at https://app.palmier.me or in the Android app. Pairing always goes through the relay; auto-LAN kicks in transparently afterward in the native app when on the same network.

Managing Clients

# List all paired devices
palmier clients list

# Revoke a specific device's access
palmier clients revoke <token>

# Revoke all clients (unpair all devices)
palmier clients revoke-all

Revoking the linked device also clears the host's linked-device record; device capabilities stop working until another paired device is linked from its drawer.

The init Command

The wizard:

• Detects installed agent CLIs and caches the result
• Asks for the HTTP port
• Detects the default network interface (used for auto-LAN)
• Shows a summary (including any existing scheduled tasks to recover) and asks for confirmation
• Registers with the Palmier server, saves configuration to ~/.config/palmier/host.json
• Installs a background daemon (systemd user service on Linux, LaunchAgent on macOS, Task Scheduler on Windows)
• Auto-enters pair mode to connect your first device

The daemon automatically recovers existing tasks by reinstalling their system timers on startup.

macOS note: Palmier installs as a user-level LaunchAgent, so it runs without sudo. LaunchAgents only run while the user is logged into the GUI session — after a reboot, scheduled tasks stay dormant until you log in at least once. Enable auto-login in System Settings → Users & Groups if you need unattended operation across reboots.

Agents are re-detected on every daemon start. Run palmier restart after installing or removing a CLI.

Re-detecting the LAN Network

The default network interface is detected once during palmier init and saved to host.json. The daemon derives the current IP live from that interface on each client connect, so DHCP-assigned IP changes on the same adapter are picked up automatically. If you physically switch to a different network adapter (e.g., plug in Ethernet after running on WiFi, or add a new USB-tethered interface), run palmier init again to re-detect.

CLI Reference

Uninstalling

To fully remove Palmier from a machine:

1. Unpair your device in the PWA (via the host menu).

2. Stop the daemon and remove all scheduled tasks:

   palmier uninstall
   

3. Uninstall the package:

   npm uninstall -g palmier
   

4. (Optional) Remove configuration and task data:

   Linux / macOS:

   rm -rf ~/.config/palmier
   rm -rf ~/palmier   # or wherever your Palmier root directory is
   

   Windows (PowerShell):

   Remove-Item -Recurse -Force "$env:USERPROFILE\.config\palmier"
   Remove-Item -Recurse -Force "$env:USERPROFILE\palmier"   # or wherever your Palmier root directory is
   

Disclaimer

Palmier spawns AI agents that can read, write, and execute on your machine. Read the full disclaimer before use. By using Palmier, you agree to the Terms of Service and Privacy Policy.

License

This project is licensed under the Apache License 2.0. See LICENSE for the full text.