Palmier

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

Palmier installs, manages, and runs AI agent CLIs (Claude Code, Gemini CLI, Codex, etc.) on your machine using your existing AI subscriptions, and exposes them to your phone through a mobile-friendly PWA and an Android app. It runs as a background daemon and is agent-agnostic — adding support for a new CLI is a config change, not a code change.

The control surface is bidirectional:

• Phone → agents: start ad-hoc sessions, register schedule- or event-triggered tasks, inspect session output, and respond to agent input/confirmation requests.
• Agents → phone: agents can read device state (location, calendar, contacts, notifications, SMS, battery) and trigger actions (push notifications, full-screen alarms, SMS, email, contact/calendar writes, ringer mode).

Capability access is opt-in per device: each capability is gated behind an Android permission and a per-host toggle. An optional yolo mode auto-approves agent input/confirmation requests.

Quick Start

1. Install Palmier and run setup:

   Linux / macOS:

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

   Windows:

   powershell -c "irm https://palmier.me/install.ps1 | iex"

   The one-liner installs Node.js 24+ if needed, installs palmier globally, and runs the setup wizard. If you already have Node.js 24+ and npm:

   npm install -g palmier && palmier init

   The wizard creates ~/palmier as the task storage directory, detects existing agent CLIs or offers to install supported ones (Claude Code, Gemini CLI, Codex CLI, GitHub Copilot, OpenClaw, or others), configures access, installs the background daemon, and starts pairing.

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

3. To access from other devices, enter the pairing code shown after init into the PWA or the Android app.

Prerequisites

• Linux with systemd, macOS 13+, or Windows 10/11

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 readily available if running agent tasks directly from Palmier app, without installing the MCP server.

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

Available tools: | Tool | Description | |------|-------------| | notify | Send a push notification to the user's device | | request-input | Request input from the user (blocks until response) | | request-confirmation | Request confirmation from the user (blocks until response) | | device-geolocation | Get GPS location of the user's mobile device | | read-contacts | Read the contact list from the user's device | | create-contact | Create a new contact on the user's device | | read-calendar | Read calendar events (with time range filter) | | create-calendar-event | Create a calendar event on the user's device | | send-sms-message | Send an SMS message from the user's device | | send-email | Send an email from the user's device (opens the email app with the draft pre-filled for review) | | send-alarm | Trigger a full-screen alarm popup with ringtone on the user's device (pierces DND) | | read-battery | Get battery level and charging status | | set-ringer-mode | Set ringer mode (normal/vibrate/silent) |

Available resources: | Resource | URI | Description | |----------|-----|-------------| | Device Notifications | notifications://device | Recent notifications from the user's Android device | | Device SMS | sms-messages://device | Recent SMS messages from the user's Android device |

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:

| Mode | Where | Pairing | Notes | |------|-------|---------|-------| | Local (browser) | http://localhost:7256 in a browser on the host machine | Not required | Loopback only. No internet or Palmier server connection needed. | | PWA | https://app.palmier.me in any browser | Required | Installable to your home screen; supports web push notifications. Always goes through the cloud relay. | | Android app | Android APK | Required | Unlocks phone capabilities (GPS, email, calendar, contacts, SMS, alarms), push notifications, and auto-LAN. |

iOS app coming soon.

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; agents previously installed by Palmier have their installed version re-probed so the recorded version stays in sync with manual upgrades
• Offers to install missing supported agents from npm (one at a time, arrow-key menu). After each install the agent's version is stamped (becoming "Palmier-managed"), the wizard kicks off authentication, and waits for you to press Enter before offering the next install. On re-init, the agents list is saved after every install so an interrupted wizard is resumable.
• 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). On re-init, also restarts the daemon so the running process picks up the new agents/versions for host.info.
• 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; managed-agent versions are re-probed live so upgrades performed outside the wizard show up automatically.

Palmier-managed Agents

An agent is considered Palmier-managed if it was installed via palmier init, palmier agents, or its update is initiated via the PWA. Palmier-managed agents have a known installed version stamped at install/update time; that version is what the PWA uses to drive the agent soft-update dialog and what's recorded into each session's run metadata so a session always shows the agent version it actually ran with — even after the live agent is upgraded.

Agents installed by the user outside the wizard (e.g., npm install -g <pkg> directly) are detected and usable but are not considered Palmier-managed. The PWA shows them under a separate "Version not managed by Palmier" section and does not offer auto-update for them.

Run palmier agents to manage agent CLIs after setup: it lists installed agents and offers an interactive picker to install or uninstall one. palmier init only prompts for an agent install when none are detected; once any agent is installed, init just lists them and continues with host registration.

Updates

• Palmier itself — when a newer version of palmier is published to npm, the PWA shows a dismissible "Update Available" dialog. Clicking "Update Now" runs npm update -g palmier on the host and restarts the daemon. Clicking "Dismiss" suppresses the dialog for that exact version (per host, per device); a future release re-arms it.
• Palmier-managed agents — same flow per agent: when npm publishes a newer version, the PWA shows an "Agent Update Available" dialog. Clicking "Update Now" runs npm update -g <pkg> on the host (no daemon restart needed). Dismissals are per host, per agent, per version.

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

| Command | Description | |---|---| | palmier init | Interactive setup wizard | | palmier agents | List, install, and uninstall agent CLIs | | palmier pair | Generate a pairing code to pair a new device | | palmier clients list | List active client tokens | | palmier clients revoke <token> | Revoke a specific client token | | palmier clients revoke-all | Revoke all client tokens | | palmier info | Show host connection info (address, mode) | | palmier serve | Run the persistent RPC handler (default command) | | palmier restart | Restart the palmier serve daemon | | palmier run <task-id> | Execute a specific task | | palmier uninstall | Stop daemon, remove all scheduled tasks, and uninstall Palmier-managed agent CLIs |

Uninstalling

To fully remove Palmier from a machine:

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

2. Stop the daemon, remove all scheduled tasks, and uninstall Palmier-managed agent CLIs:

   palmier uninstall

   Agents you installed yourself outside Palmier (no managed version stamp) are left in place.

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.