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

# MeepaGateway

> Connect MeepaGateway AI agents to your MeepaChat instance

## Overview

[MeepaGateway](https://github.com/bogpad/meepagateway) is a self-hosted bot gateway that connects AI agents (Claude, GPT-4, etc.) to chat platforms. The MeepaChat connector uses the [Bot Gateway WebSocket](/meepachat/bot-gateway) to receive real-time events and the REST API to send responses.

## Step 1: Create a bot in MeepaChat

You need a bot account for MeepaGateway to authenticate with. Create one using any of these methods:

Go to **Server Settings → Bots → Create Bot**. Enter a username and display name, then click **Create**. Copy the bot token immediately — it's only shown once.

Or use the CLI:

```bash theme={null}
meepachat bots create --username meepa --server <serverID>
```

Save the bot token — it has the format `BOT_ID.SECRET` and is only shown once.

<Warning>
  Treat bot tokens like passwords. Never commit them to source control.
</Warning>

## Step 2: Install MeepaGateway

<CodeGroup>
  ```bash Homebrew (macOS/Linux) theme={null}
  brew install bogpad/tap/meepagateway
  ```

  ```bash Install script theme={null}
  curl -fsSL https://meepagateway.bogpad.com/install.sh | sh
  ```

  ```bash Docker theme={null}
  docker pull ghcr.io/bogpad/meepagateway:latest
  ```
</CodeGroup>

## Step 3: Configure the MeepaChat connector

Add a MeepaChat connector to your agent's config. In `~/.meepagateway/agents/<id>/agent.yaml`:

```yaml theme={null}
connectors:
  - type: meepachat
    url: "wss://your-meepa-instance.example.com/api/bot-gateway"
    bot_token: "YOUR_BOT_ID.YOUR_BOT_SECRET"
```

Store the token in an environment variable instead of the config file:

```bash theme={null}
export MEEPA_BOT_TOKEN="YOUR_BOT_ID.YOUR_BOT_SECRET"
```

Then reference it in the config:

```yaml theme={null}
connectors:
  - type: meepachat
    url: "wss://your-meepa-instance.example.com/api/bot-gateway"
    bot_token: "$MEEPA_BOT_TOKEN"
```

## Step 4: Configure an AI provider

In `~/.meepagateway/config.yaml`:

```yaml theme={null}
providers:
  primary: anthropic
  providers:
    anthropic:
      api_key_env: ANTHROPIC_API_KEY
      model: claude-sonnet-4-6
```

Set your API key:

```bash theme={null}
export ANTHROPIC_API_KEY="sk-ant-..."
```

## Step 5: Start the gateway

```bash theme={null}
meepagateway start
```

MeepaGateway connects to your MeepaChat instance, receives a `ready` event with the bot's servers and channels, and begins responding to messages.

## Self-hosted considerations

| Setup          | URL format                                | Notes                   |
| -------------- | ----------------------------------------- | ----------------------- |
| Same machine   | `ws://localhost:8091/api/bot-gateway`     | No TLS needed           |
| Local network  | `ws://192.168.1.50:8091/api/bot-gateway`  | Use IP or local DNS     |
| Tailscale      | `wss://chat.your-tailnet/api/bot-gateway` | Both hosts on Tailscale |
| Public domain  | `wss://chat.example.com/api/bot-gateway`  | Needs valid TLS cert    |
| Docker network | `ws://meepachat:8091/api/bot-gateway`     | Same compose stack      |

### Self-signed certificates

For instances with a private CA:

```bash theme={null}
export SSL_CERT_FILE=/path/to/ca.crt
meepagateway start
```

Or disable TLS verification (not recommended for production):

```yaml theme={null}
connectors:
  - type: meepachat
    url: "wss://chat.internal/api/bot-gateway"
    bot_token: "$MEEPA_BOT_TOKEN"
    tls_verify: false
```

## How it works

1. MeepaGateway opens a WebSocket to `/api/bot-gateway` using the bot token
2. MeepaChat sends a `ready` event with all servers and channels the bot belongs to
3. The gateway auto-subscribes to all accessible channels
4. Incoming `message.created` events are routed to the configured AI agent
5. The agent's response is sent back via `POST /api/servers/{id}/channels/{id}/messages`

## Credential Action Cards

MeepaGateway agents can store logins, API keys, and passwords through interactive **action cards** rendered directly in chat. When an agent needs to store a credential, it sends a form to the conversation. You fill in the fields and confirm — the credential is encrypted and saved in the agent's credential store.

For this to work, MeepaChat must know where the gateway is running. Add `gateway_api_url` to your MeepaChat config:

```yaml theme={null}
# ~/.meepachat/config.yaml
gateway_api_url: http://localhost:63372
```

Or set the environment variable:

```bash theme={null}
export GATEWAY_API_URL=http://localhost:63372
```

<Warning>
  Without `gateway_api_url`, action cards will render in chat but the confirm/reject buttons will fail silently. The gateway URL must be reachable from the MeepaChat server (not the browser).
</Warning>

### How it works

1. The agent calls the `credential` tool with action `add_credential`
2. MeepaGateway sends a message to the chat channel with form metadata
3. MeepaChat renders the message as an interactive action card
4. You fill in the fields (service, username, password) and click **Submit**
5. MeepaChat proxies the confirmation to the gateway at `gateway_api_url`
6. The gateway encrypts and stores the credential in the agent's SOPS-encrypted credential file

See the [MeepaGateway credentials documentation](/gateway/credentials) for full details on credential categories, provisioning, and the credential store.

***

For detailed Gateway configuration — agents, skills, cron jobs, and multi-agent routing — see the [MeepaGateway documentation](/gateway/introduction).