Polyant

🌐 Website: polyant.ai  ·  📚 Docs: docs.polyant.ai  ·  💬 GitHub: polyant-ai/polyant

Polyant is an enterprise AI platform by Exelab for putting agents to work in business processes, at scale. It is open source under AGPL-3.0-or-later and provides a complete runtime for multi-agent systems with an OpenAI-compatible API, a NestJS engine, and a Next.js admin panel — batteries included.

Polyant v1.3.4 is the current stable release. Review the changelog, the release notes, and the GitHub release. Upgrading from 1.1.x to 1.2.0 needs operator action — read the upgrade guide first. In a running admin installation, version and release details are available at /about.

The name comes from Hofstadter's Gödel, Escher, Bach — specifically the "Ant Fugue" dialogue and the character of Aunt Hillary, an ant colony understood as the archetype of emergent intelligence: individual agents, each one limited, that produce — by coordinating — a collective intelligent behaviour that exceeds the sum of its parts. It is, literally, the thesis we are pitching: fleets of specialised agents that, when orchestrated, generate performance impossible for any single agent. Poly- (classical Greek, "many") makes the key concept explicit: coordinated multiplicity.

Many agents. One mind.

Polyant grew out of taking OpenClaw apart and asking a different question: what does it take to run that kind of assistant inside an organization? The answer produced a multi-instance model, an admin panel as the primary surface, per-instance secret encryption, a proactive Room engine next to the reactive chat loop, and an OpenAI-compatible API as the default integration surface.

Read the long version in Why Polyant.

• Supervisor Agent — Central orchestrator with tool use, up to 15 reasoning steps per request (Vercel AI SDK)
• Long-term Memory — Automatic fact extraction via LLM; hybrid search with pgvector cosine similarity + PostgreSQL FTS fused via Reciprocal Rank Fusion
• Multi-channel — Telegram, Slack, WhatsApp, and a Web channel with an OpenAI-compatible HTTP API (with file attachment support). Web is a channel like the others and starts off for a new agent
• Provider-agnostic — Switch between OpenAI, Anthropic, Amazon Bedrock, and Nebius Token Factory per agent from the admin panel; the embedding provider is chosen independently of the chat provider. A tier abstraction (fast | standard | heavy) decouples code from model names, and a model catalog carries per-model pricing, vision, reasoning, and prompt-caching capabilities
• Tools & Plugins — Author a tool as export default defineTool(...) from @polyant-ai/plugin-sdk; the engine loader collects it at boot with no wiring. Tools live in-engine or in external plugin repos loaded via PLUGIN_DIRS — see Plugins & the SDK
• MCP Client — Equip an agent with tools from external Model Context Protocol servers, configured per agent. Three auth modes (none for public or network-isolated servers, static for a bearer token or custom header, oauth for OAuth 2.1 including Dynamic Client Registration); credentials are stored AES-256-GCM encrypted and never returned by the API. A slow or dead server is skipped for the turn rather than stalling it, on a connect budget set in Settings → General
• A2A Server — Expose an agent to other agents over the Agent2Agent protocol: an Agent Card at GET /a2a/:slug/.well-known/agent-card.json and JSON-RPC at POST /a2a/:slug/jsonrpc. Opt-in per agent (a2a_enabled, default off, independent of the Web channel) and authenticated with the agent's own API key
• Skill System — Markdown-based skill definitions stored in the database; per-instance encrypted env vars for skills that need API keys
• Multi-instance — Independent configuration of prompts, skills, tool availability, and identity per instance; instances exposed as selectable "models" via the OpenAI-compatible API
• Per-instance Secrets — API keys, channel config, and LangSmith settings stored AES-256-GCM encrypted per instance
• RBAC — Organization → Workspace → Agent tenancy with four system roles (Owner / Admin / Member / Viewer) and a resource:action permission matrix, enforced unconditionally (no shadow mode, no opt-out); membership is granted deliberately by an administrator, never by signing in
• Admin Panel — Next.js 16 frontend for managing instances, conversations, memories, skills, tools, channels, and analytics
• Event-driven Room — Proactive agent workspace that processes webhook events on a 30-second tick and can push outbound messages
• Conversation Tracking — Full message history with summaries and full-text search in PostgreSQL
• Analytics — Token usage, cost tracking, and pipeline latency per instance
• Cost Monitoring — Every LLM call logged with token counts and estimated USD cost
• File Attachments — Photos and PDFs from WhatsApp/Telegram stored in S3, passed as multimodal content to the LLM
• Voice Messages — Inbound audio transcribed per agent via OpenAI Whisper, Amazon Transcribe, or Deepgram — or turned off explicitly
• Knowledge Base — Per-agent documents chunked and retrieved with pgvector, editable from the panel and portable as a JSON bundle
• Lifecycle Hooks — Typed code hooks at four fixed pipeline points that can inject context, halt a turn and answer, or replace the generated reply
• Scheduled Tasks — Cron-style prompts an agent runs on its own, with a per-run log
• Agent-to-Agent (in-process) — Beyond the A2A protocol above, an agent in the same deployment can be called as an ask_<slug> tool, bounded to one hop
• GDPR Opt-out — Deterministic STOP/START keyword gate per contact, enforced in code rather than by the model, blocking inbound and proactive outbound alike
• Export & Import — A full agent configuration (prompts, skills, tools, channels, hooks, MCP servers, Room, tasks) travels as a JSON bundle; secrets are never exported

The full documentation lives at docs.polyant.ai (source: polyant-ai/docs).

• Getting Started — build your first agent in 10 minutes
• Channels Setup — Telegram, Slack, WhatsApp recipes
• Examples — minimal instance, skill, and tool templates

• Deployment — Docker Compose, Render, Fly.io, Kubernetes
• Upgrading — version-to-version upgrade steps that need an operator decision

• Architecture — full technical deep dive
• Glossary — Instance, Tier, Room, Skill, Tool explained

• Node.js 24+
• Docker & Docker Compose

git clone https://github.com/polyant-ai/polyant.git
cd polyant
npm install

cp .env.example .env

Generate the required secrets and paste each into .env:

openssl rand -hex 32   # → ENCRYPTION_KEY
openssl rand -hex 32   # → AUTH_SECRET
openssl rand -hex 32   # → AUTH_INTERNAL_SECRET (without it nobody can sign in to the panel)

The sample database password is changeme, set in both POSTGRES_PASSWORD and DATABASE_URL. It works for a local machine as it is. If you change it, change it in both places: the container takes POSTGRES_PASSWORD, the engine connects with DATABASE_URL.

Set the initial admin account in .env. The admin is created when the engine first boots, and the panel asks for a new password at the first sign-in:

INITIAL_ADMIN_EMAIL=admin@example.com
INITIAL_ADMIN_PASSWORD=choose-a-strong-password

The admin panel (Next.js) does not read the root .env. Create packages/web/.env.local with the same secrets and the database:

# packages/web/.env.local

AUTH_SECRET=<same value as .env>
AUTH_INTERNAL_SECRET=<same value as .env>
AUTH_TRUST_HOST=true
DATABASE_URL=postgresql://polyant:changeme@localhost:5432/polyant   # same password as .env
NEXT_PUBLIC_API_URL=http://localhost:4000
INTERNAL_ENGINE_URL=http://localhost:4000

docker compose up -d --wait

Starts PostgreSQL 16 with pgvector on port 5432 and returns once the database accepts connections. Compose reads POSTGRES_PASSWORD from .env, so step 2 comes first.

npm run db:migrate   # create all tables
npm run dev          # engine on :4000
npm run dev:web      # admin panel on :3000 (separate terminal)

Open http://localhost:3000 and sign in with INITIAL_ADMIN_EMAIL and INITIAL_ADMIN_PASSWORD. The panel asks you to choose a new password, then create an agent and open its Model section to set the provider key for each task (Conversation, Embeddings).

┌──────────────────────────────────────────────┐
│         packages/web  (Next.js 16)           │
│     Admin Panel — instance management        │
└─────────────────┬────────────────────────────┘
                  │ REST API + cookie auth
┌─────────────────┴────────────────────────────┐
│        packages/engine  (NestJS 12)          │
├──────────────────────────────────────────────┤
│  HTTP Server     OpenAI-compatible API       │
│  Channel Layer   Telegram · Slack · WhatsApp │
│  Agent Layer     Supervisor + Tool Registry  │
│  Memory Layer    pgvector + PG FTS + LLM     │
│  AI Gateway      Tier abstraction + logging  │
│  Room Engine     Event-driven proactive loop │
│  Crypto Layer    AES-256-GCM encryption      │
│  Data Layer      PostgreSQL 16 (Drizzle ORM) │
└──────────────────────────────────────────────┘

See Architecture for the full technical reference.

All channel configs are stored encrypted per-instance. Adapters start/stop dynamically without a restart.

Scripts and polyant-cli call the engine's management API with a management API key in the X-Polyant-Key header. An organization Owner issues one from API keys in the panel's organization navigation: give it a name and, optionally, an expiry, then copy the token, which is shown only once. A key acts with the Owner permission set within its organization until it expires or is revoked from the same page, and it cannot issue or revoke keys itself.

curl -H "X-Polyant-Key: $POLYANT_KEY" http://localhost:4000/api/instances

Polyant is framework-first — it ships generic tools, and domain-specific ones (a CRM's booking flow, a billing lookup) live in plugins: external git repos of tool files the engine loads at boot. A tool is a *.tool.ts file that default-exports a defineTool(...) from @polyant-ai/plugin-sdk, a small stateless contract package:

import { defineTool } from "@polyant-ai/plugin-sdk";
import { z } from "zod";

export default defineTool({
  name: "bookAppointment",
  description: "Book an appointment in the CRM.",
  parameters: z.object({ patientId: z.string(), date: z.string() }),
  execute: async (input, ctx) => ({ status: "booked" }),
});

defineTool serializes the static Zod schema to JSON Schema inside your plugin's own realm, so the engine and each plugin resolve their own copies of the SDK without breakage. Point the engine at a plugin repo with PLUGIN_DIRS, or drop it into packages/engine/src/plugins/.

Full authoring reference — schema rules, plugin.json, module resolution, the symlink trap: docs/plugins.md and the SDK README.

Semantic Versioning applies to the documented OpenAI-compatible API, Plugin SDK and manifest, and documented configuration and migration behavior. Internal engine modules and the admin UI are not public SemVer surfaces.

To upgrade an existing development installation, back up PostgreSQL, then run:

npm ci
npm run db:migrate
npm run build

Restart the services, then smoke-test sign-in and a representative chat.

See ROADMAP.md for the direction, and GitHub Issues and Discussions for the live list of planned work and open requests.

Contributions are welcome! Please read CONTRIBUTING.md for setup instructions, coding conventions, and the PR process.

For vulnerability reports, see SECURITY.md — please do not file public issues for security bugs.

Polyant is licensed under the GNU Affero General Public License v3.0.