> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agdi

# Agdi 🦞

![Agdi](https://mintlify.s3.us-west-1.amazonaws.com/agdiai-597e782f/assets/agdi-logo-text-dark.png)

> *"EXFOLIATE! EXFOLIATE!"* — A space lobster, probably

**Any OS gateway for AI agents across WhatsApp, Telegram, Discord, iMessage, and more.**\

Send a message, get an agent response from your pocket. Plugins add Mattermost and more.

> [card] [Get Started](https://agdiai-597e782f.mintlify.site/start/getting-started.md)
>
> Install Agdi and bring up the Gateway in minutes.

> [card] [Run Onboarding](https://agdiai-597e782f.mintlify.site/start/wizard.md)
>
> Guided setup with `agdi onboard` and pairing flows.

> [card] [Open the Control UI](https://agdiai-597e782f.mintlify.site/web/control-ui.md)
>
> Launch the browser dashboard for chat, config, and sessions.

## What is Agdi?

Agdi is a **self-hosted gateway** that connects your favorite chat apps — WhatsApp, Telegram, Discord, iMessage, and more — to AI coding agents like Pi. You run a single Gateway process on your own machine (or a server), and it becomes the bridge between your messaging apps and an always-available AI assistant.

**Who is it for?** Developers and power users who want a personal AI assistant they can message from anywhere — without giving up control of their data or relying on a hosted service.

**What makes it different?**

* **Self-hosted**: runs on your hardware, your rules
* **Multi-channel**: one Gateway serves WhatsApp, Telegram, Discord, and more simultaneously
* **Agent-native**: built for coding agents with tool use, sessions, memory, and multi-agent routing
* **Open source**: MIT licensed, community-driven

**What do you need?** Node 24 (recommended), or Node 22 LTS (`22.14+`) for compatibility, an API key from your chosen provider, and 5 minutes. For best quality and security, use the strongest latest-generation model available.

## How it works

```mermaid theme={"theme":{"light":"min-light","dark":"min-dark"}}
flowchart LR
  A["Chat apps + plugins"] --> B["Gateway"]
  B --> C["Pi agent"]
  B --> D["CLI"]
  B --> E["Web Control UI"]
  B --> F["macOS app"]
  B --> G["iOS and Android nodes"]
```

The Gateway is the single source of truth for sessions, routing, and channel connections.

## Key capabilities

> [card] Multi-channel gateway
>
> WhatsApp, Telegram, Discord, and iMessage with a single Gateway process.

> [card] Plugin channels
>
> Add Mattermost and more with extension packages.

> [card] Multi-agent routing
>
> Isolated sessions per agent, workspace, or sender.

> [card] Media support
>
> Send and receive images, audio, and documents.

> [card] Web Control UI
>
> Browser dashboard for chat, config, sessions, and nodes.

> [card] Mobile nodes
>
> Pair iOS and Android nodes for Canvas, camera, and voice-enabled workflows.

## Quick start

**1. Install Agdi**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
npm install -g agdi@latest
```

**2. Onboard and install the service**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi onboard --install-daemon
```

**3. Chat**

Open the Control UI in your browser and send a message:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi dashboard
```

Or connect a channel ([Telegram](https://agdiai-597e782f.mintlify.site/channels/telegram.md) is fastest) and chat from your phone.

Need the full install and dev setup? See [Getting Started](https://agdiai-597e782f.mintlify.site/start/getting-started.md).

## Dashboard

Open the browser Control UI after the Gateway starts.

* Local default: [http://127.0.0.1:18789/](http://127.0.0.1:18789/)
* Remote access: [Web surfaces](https://agdiai-597e782f.mintlify.site/web.md) and [Tailscale](https://agdiai-597e782f.mintlify.site/gateway/tailscale.md)

![Agdi](https://mintlify.s3.us-west-1.amazonaws.com/agdiai-597e782f/whatsapp-agdi.jpg)

## Configuration (optional)

Config lives at `~/.agdi/agdi.json`.

* If you **do nothing**, Agdi uses the bundled Pi binary in RPC mode with per-sender sessions.
* If you want to lock it down, start with `channels.whatsapp.allowFrom` and (for groups) mention rules.

Example:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  messages: { groupChat: { mentionPatterns: ["@agdi"] } },
}
```

## Start here

> [card] [Docs hubs](https://agdiai-597e782f.mintlify.site/start/hubs.md)
>
> All docs and guides, organized by use case.

> [card] [Configuration](https://agdiai-597e782f.mintlify.site/gateway/configuration.md)
>
> Core Gateway settings, tokens, and provider config.

> [card] [Remote access](https://agdiai-597e782f.mintlify.site/gateway/remote.md)
>
> SSH and tailnet access patterns.

> [card] [Channels](https://agdiai-597e782f.mintlify.site/channels/telegram.md)
>
> Channel-specific setup for WhatsApp, Telegram, Discord, and more.

> [card] [Nodes](https://agdiai-597e782f.mintlify.site/nodes.md)
>
> iOS and Android nodes with pairing, Canvas, camera, and device actions.

> [card] [Help](https://agdiai-597e782f.mintlify.site/help.md)
>
> Common fixes and troubleshooting entry point.

## Learn more

> [card] [Full feature list](https://agdiai-597e782f.mintlify.site/concepts/features.md)
>
> Complete channel, routing, and media capabilities.

> [card] [Multi-agent routing](https://agdiai-597e782f.mintlify.site/concepts/multi-agent.md)
>
> Workspace isolation and per-agent sessions.

> [card] [Security](https://agdiai-597e782f.mintlify.site/gateway/security.md)
>
> Tokens, allowlists, and safety controls.

> [card] [Troubleshooting](https://agdiai-597e782f.mintlify.site/gateway/troubleshooting.md)
>
> Gateway diagnostics and common errors.

> [card] [About and credits](https://agdiai-597e782f.mintlify.site/reference/credits.md)
>
> Project origins, contributors, and license.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.