Skip to content

Manage agent local database files and installations

Each XMTP agent installation maintains its own local database containing message history, conversation state, and cryptographic material. When you delete this database (or use an in-memory database), you create a new installation that counts toward your installation limits.

Installation limits and revocation rules

Understanding XMTP's installation and inbox limits is critical for production deployments:

  • Installation limit per inbox: Each inbox supports up to 10 active installations. Once you reach this limit, you must revoke an existing installation before adding a new one.

  • Update limit per inbox: Every installation addition or revocation counts toward a cumulative limit of 256 inbox updates. Exceeding this threshold requires inbox rotation, which permanently removes access to all historical conversations for that inbox.

These limits protect inbox integrity and prevent unbounded key state growth across devices. For production environments, always use persistent volumes to back up and preserve your database across agent restarts.

Understand local database files

The Agent SDK creates database files in the dbPath directory (default is '/'). These files store your agent's identity and message history.

Database file naming:

Database files follow this pattern: xmtp-{environment}-{inbox-id}.db3

Example:

xmtp-production-62ff7c82fa2e8c9a0a0c9e58e7247704d102c41e5ceb4dc3573792d7d7a1c688.db3
  • xmtp-production: Environment prefix
  • 62ff7c82fa2e8c9a0a0c9e58e7247704d102c41e5ceb4dc3573792d7d7a1c688: Inbox ID (Your xmtp identity)
  • .db3: SQLite database file extension

Understand installations

With XMTP, your agent has an inbox that you use to access its messages. An inbox can have multiple identities associated with it. Your agent's identity has a kind (such as EOA or SCW) and a string, which in the case of an EOA or SCW, is an Ethereum address. All messages associated with your agent's identity flow through the one inbox ID.

When you deploy your agent to a platform, you create an XMTP client for your agent. The client creates an inbox ID and installation ID associated with your agent's identity. Each time you deploy your agent to a new platform, it creates a new installation for the same inbox ID. The installation represents your agent running on that specific platform.

For example, consider deploying your agent to these platforms:

  • Local development: Creates an installation
  • Railway: Creates another installation
  • Production server: Creates another installation

Your agent can have up to 10 active installations before you need to revoke one to add another. Installations only accumulate for agent deployments using the same XMTP network environment, such as local, dev, or production.

For example, if you deploy your agent across these network environments, you will have 3 inboxes, each with 1 installation:

  • Local development: local network
  • Railway: dev network
  • Production server: production network
Diagram showing agent deployments across different network environments (local, dev, production) creating separate inboxes with one installation each

If you deploy your agent to this same network environment, you have 1 inbox with 3 installations:

  • Local development: production network
  • Railway: production network
  • Production server: production network
Diagram showing agent deployments to the same production network environment creating one inbox with three installations

Revoke agent installations

When you revoke an agent installation, it can no longer send or receive messages. However, you can still access the local database. Your agent can still run from any active installations on other deployment platforms.

  1. Web tool: xmtp.chat/inbox-tools
  2. CLI script: revokeInstallations.ts in the xmtp-agent-examples repo
yarn revoke <inbox-id> <installations-to-exclude>