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)

# One-line installer for the CLI and postinstall flow
curl -fsSL https://raw.githubusercontent.com/xenoISA/isA_Mate/main/install.sh | bash

# Or install directly with pip
pip install isa-mate

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

# Start the gateway server
isa-mate serve

From a local isA_Mate checkout, bring up the full local stack:

isa up
# Web:      http://localhost:4100
# Gateway:  http://localhost:18789
# Model:    http://localhost:8082
# Proxy:    http://localhost:5005/v1

isa status    # port + health + ownership per service (non-zero if core is down)
isa restart   # down tracked services, then up
isa down

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/chat \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"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 up	Bring up the local model + gateway + web stack
isa status	Report port + health + ownership per stack service
isa restart	Restart the local stack (down tracked services, then up)
isa down	Stop services tracked by the last isa up
isa-mate doctor	Run diagnostics
isa-mate accounts	Manage subscription accounts

Running Tests (local verification gate)

isA does not use GitHub Actions — the local run below IS the merge gate (#810).

make verify        # full gate: integration + smoke + full unit/component
make verify-fast   # quick subset: integration + smoke
make smoke         # standalone no-cloud smoke test only
make lint          # opt-in ruff (no repo baseline yet — lint files you touched)

make verify is the full merge gate (integration + smoke + full unit/component). make verify-fast is the quick subset (integration + smoke) for tight loops — always finish with a full make verify before landing.

Releasing

isA does not release through GitHub Actions — it is billing-blocked org-wide, which is exactly how PyPI sat at 0.2.0 (2026-06-16) while main reached 0.4.x and every new user's curl … | bash install got a package three minor versions stale (#1280). .github/workflows/publish.yml is dormant; the local gate below IS the publish path.

make verify                              # the merge gate must be green first
# bump `version` in pyproject.toml, commit, then tag vX.Y.Z

RELEASE_TAG=vX.Y.Z make publish-dry      # build + verify, uploads nothing
RELEASE_TAG=vX.Y.Z make publish-pypi     # upload to PyPI + attach to the GH release

publish-pypi needs PYPI_API_TOKEN in the release owner's environment. It fails closed — publishing is irreversible, so it refuses when the committed version and the tag disagree, when the version already exists on PyPI (or the index can't be read), when dist/ holds a stale artifact from another version, when the wheel is missing package data the build config declares, or when the token looks like a .env placeholder rather than a real pypi- token.

A tag is not a release. Until publish-pypi runs, the version exists on GitHub and nowhere users install from.

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