Mirai Agent

A Hermes-style personal AI agent for your machine: interactive CLI, headless WebSocket serve for the desktop app, SKILL.md skills, memory, MCP tools, and optional messaging gateways — all powered by Mirai on satuapps.com.

What it is

One agent core, thin I/O shells. The model backend is the Mirai cloud API (compatible chat completions with tool calling and billing). Identity and memory live under ~/.mirai-agent; tools and skills run on your machine.

Install

From a checkout of this repo (Python 3.11+, uv). Until the package is on PyPI, this is the supported path:

cd agent && uv sync && uv run mirai-agent

After publish you will be able to install with pip or uv, for example:

One-liner (coming once published):

pip install "mirai-agent[all]"

uv tool install "mirai-agent[all]"

Quick start

Create an API key on the site (Chat → Settings → API key), then export it or put it in config:

export MIRAI_API_KEY=mirai-…

Interactive REPL (prompt_toolkit + Rich, slash commands):

mirai-agent

One-shot turn:

mirai-agent -p "what files are in this repo?"

Headless WebSocket server for the desktop app (default :9199):

mirai-agent serve

Messaging gateway daemon (Telegram / Discord / Slack / WhatsApp / webhook):

mirai-agent gateway run

Config

Home directory is ~/.mirai-agent (override with MIRAI_AGENT_HOME). Put your key in MIRAI_API_KEY or in config.yaml. Sessions, memory, skills, and permissions live there too.

Minimal config.yaml:

api_key: mirai-…
# optional:
# model: mirai-v1-code
# base_url: https://satuapps.com/v1

Skills

Add SKILL.md files (YAML frontmatter, agentskills.io-compatible) under ~/.mirai-agent/skills/ or the bundled skills dir. The agent indexes them in context and loads the full body via a skill_view tool when needed.

Messaging channels

mirai-agent gateway run connects configured platforms (Telegram long-poll, Discord Gateway, Slack Socket Mode, WhatsApp Cloud API, generic HTTP webhook), allowlists chats, maps each chat to a persistent session, and replies through the same agent core. Default permission mode is read-only. Set platform tokens in env or gateway.* in config. See the agent README for full YAML.

Desktop apps (macOS / Windows / Linux)

Native Electron apps spawn mirai-agent serve and talk over the WebSocket JSON-RPC protocol. Unsigned beta installers (macOS arm64 DMG/ZIP, Windows x64 NSIS) ship from GitHub Releases via the desktop CI workflow; a Linux build is planned next. Gatekeeper and SmartScreen warnings are expected until Apple notarization and Windows signing land.

Open GitHub Releases for the latest DMG / NSIS builds (no fixed version pinned here). GitHub Releases.

Self-host

mirai-agent is local-first by design. Identity, sessions, memory, skills, and permissions live under ~/.mirai-agent (override with MIRAI_AGENT_HOME). Tools and skills execute on your machine; only the model completions go through the Mirai cloud API at satuapps.com/v1. Run it on a laptop, a server, or a single-board computer — no managed control plane required.

Prefer the Node terminal agent instead? Read the Mirai CLI docs · Building on the HTTP API directly? Read the API docs.