MeepaGateway

Connect MeepaGateway AI agents to your MeepaChat instance

Overview

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 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:

meepachat bots create --username meepa --server <serverID>

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

Treat bot tokens like passwords. Never commit them to source control.

Step 2: Install MeepaGateway

Homebrew (macOS/Linux)

brew install bogpad/tap/meepagateway

Step 3: Configure the MeepaChat connector

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

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:

export MEEPA_BOT_TOKEN="YOUR_BOT_ID.YOUR_BOT_SECRET"

Then reference it in the config:

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:

providers:
  primary: anthropic
  providers:
    anthropic:
      api_key_env: ANTHROPIC_API_KEY
      model: claude-sonnet-4-6

Set your API key:

export ANTHROPIC_API_KEY="sk-ant-..."

Step 5: Start the gateway

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:

export SSL_CERT_FILE=/path/to/ca.crt
meepagateway start

Or disable TLS verification (not recommended for production):

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:

# ~/.meepachat/config.yaml
gateway_api_url: http://localhost:63372

Or set the environment variable:

export GATEWAY_API_URL=http://localhost:63372

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).

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 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.