Skip to content

Debug an agent

You can debug and interact with your agent using xmtp.chat, the official web chat app for developers.

Be sure to point xmtp.chat to the XMTP environment set in your agent's .env file.

Run a local XMTP network

dev and production networks are hosted by XMTP, while you can run your own local network.

  1. Install Docker

  2. Start the XMTP service and database

    ./dev/up
  3. Change the .env file to use the local network

    XMTP_ENV = local
  4. Try out the example agents using xmtp.chat, the official web inbox for developers.

    xmtp.chat DM screenshot

Enable debug logging

To activate detailed debugging logs, set the XMTP_FORCE_DEBUG environment variable in your .env file:

XMTP_FORCE_DEBUG=true

This will enable verbose logging throughout the XMTP Agent SDK, helping you troubleshoot issues and understand the internal flow of messages and events.

Debug agent information

You can use this code to get your agent's client information, which provides useful values for debugging:

Node
// Log when we're ready
agent.on('start', (): void => {
  logDetails(agent.client);
});

Example output:

 XMTP Client:
 InboxId: 21313b5f4f2dd2dc063762eb939d3596229c30de1128826727154da5b28be0a5
 Version: HEAD@a9d19aa (2025-08-25 21:45:01 +0000)
 Address: 0xadc58094c42e2a8149d90f626a1d6cfb4a79f002
 Conversations: 0
 Installations: 5
 InstallationId: 3c072cd74f2f95185c068cf7ea9ee5a22bef5b42a1630749d9e0be8b7a27fe22
 Key Package created: 9/19/2025, 7:07:30 PM
 Key Package valid until: 12/12/2025, 8:07:30 PM
 Networks: production
 URL: http://xmtp.chat/dm/0xadc58094c42e2a8149d90f626a1d6cfb4a79f002