isa-mate 0.2.0

isA Mate - The default agent app of the isA platform

isA Mate

The default agent app of the isA platform. A personal AI companion that connects to any messaging platform and runs locally or in the cloud.

Features

• Multi-channel: Telegram, Discord, Slack, WhatsApp, Feishu, Signal, Teams, Matrix (and more coming)
• Multi-model: Route through Anthropic, OpenAI, or local Ollama models
• Multi-agent: Hybrid A2A delegation across pinned platform teams and dynamically discovered org agents
• Memory: Persistent conversation memory with SQLite or remote backends
• Tools: 190+ tools via MCP (Model Context Protocol)
• Local-first: Runs on your machine with optional cloud deployment

Quick Start

Option A: pip install (recommended)

pip install isa-mate

# Interactive setup — picks your model provider, channels, etc.
isa-mate init

# Start the gateway server
isa-mate serve

Option B: Docker (one command)

docker run -e ANTHROPIC_API_KEY=sk-... -p 18789:18789 ghcr.io/xenoisa/isa-mate

Or with Docker Compose for the full stack:

git clone https://github.com/xenoISA/isA_Mate.git && cd isA_Mate
echo "ANTHROPIC_API_KEY=sk-..." > .env
docker compose up

Verify it's running

# Health check
curl http://localhost:18789/health

# Send a message
curl -X POST http://localhost:18789/v1/query \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Hello!"}'

Requirements

• Python 3.10+ (pip install) or Docker
• An AI model provider (Ollama for free local models, or Anthropic/OpenAI subscription)
• If using a subscription provider (anthropic-sub / codex-sub): SUBSCRIPTION_PROXY_URL pointing at an isa_model deployment. The subscription proxy lives in isa_model since xenoISA/isA_Model#901 — Mate no longer starts it locally. See docs/guides/subscription_proxy_migration.md in the isa_model repo.

Commands

Command	Description
isa-mate init	Interactive setup wizard
isa-mate serve	Start gateway server
isa-mate cli	Interactive terminal mode
isa-mate query "..."	One-shot query
isa-mate doctor	Run diagnostics
isa-mate accounts	Manage subscription accounts

Connecting Channels

After setup, connect your favorite messaging platform:

Telegram

# 1. Create a bot via @BotFather, get your token
# 2. Set the token
export TELEGRAM_BOT_TOKEN=your-token-here

# 3. Start with Telegram enabled
isa-mate serve

Discord

# 1. Create a Discord bot at https://discord.com/developers
# 2. Set the token
export DISCORD_BOT_TOKEN=your-token-here

# 3. Install the channels extra
pip install isa-mate[channels]

# 4. Start
isa-mate serve

Slack

# 1. Create a Slack app at https://api.slack.com/apps
# 2. Set credentials
export SLACK_BOT_TOKEN=xoxb-...
export SLACK_SIGNING_SECRET=your-secret

# 3. Start
isa-mate serve

See Channel Integrations Guide for all supported platforms.

Configuration

Configuration is stored at ~/.isa/mate/config.yaml. Run isa-mate init to generate it interactively, or use --non-interactive mode with environment variables:

ISA_MATE_MODEL=llama3 ISA_MATE_PROVIDER=ollama isa-mate init --non-interactive

Mate delegation supports a hybrid routing model:

• Pinned core teams from teams.entries
• Dynamic org-agent lookup from teams.directory
• Per-request shortlisting before the model decides whether to delegate

Environment Variables

Variable	Default	Description
ISA_MATE_HOST	127.0.0.1	Gateway bind host
ISA_MATE_PORT	18789	Gateway bind port
ISA_MATE_MODEL	gpt-5-nano	Model name
ISA_MATE_PROVIDER	(empty)	Provider: anthropic-sub, codex-sub, ollama
ISA_MATE_EXECUTION_MODE	reactive	Agent execution mode
ANTHROPIC_API_KEY	(empty)	Anthropic API key (for Docker)

Deployment Modes

• Local-first (isa-mate serve): Run on your machine
• Docker (docker compose up): Containerized with health checks
• Cloud (isa-mate cloud): Headless cloud deployment
• Pool (isa-mate pool): Shared pool mode for multi-tenant setups

isA Mate vs OpenClaw

Capability	isA Mate	OpenClaw
Setup	pip install isa-mate && isa-mate init	Clone repo + manual config
Docker	docker run ... ghcr.io/xenoisa/isa-mate	No official image
Channels	8+ (Telegram, Discord, Slack, WhatsApp, ...)	API only
Multi-model	Anthropic, OpenAI, Ollama, local	Single provider
Multi-agent	Hybrid A2A delegation	Single agent
Tools	190+ via MCP	Plugin-based
Memory	SQLite/remote with compaction	In-memory
Local-first	Yes — runs on your laptop	Server-only

License

MIT