Manage agent 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

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

Here are some best practices for agent installation management:

• Configure your deployments to preserve the agent's database
• Consider how many platforms you'll need before hitting the 10 installation limit
• Keep track of which installation corresponds to which platform
• Regularly check how many installations your agent has
• Revoke installations from platforms you no longer use

Common agent installation scenarios

Deploy to a new platform

When you deploy your agent to a new platform (e.g., from Railway to Fly.io):

• Your agent creates a new installation for the new platform
• If you already have 10 installations, you'll need to revoke one first
• The new installation will start fresh without conversation history

Update an existing deployment

When you redeploy your agent to the same platform:

• If the platform preserves the database, the same installation continues working
• If the platform doesn't preserve the database, a new installation is created

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.

To revoke an agent installation, use revokeInstallations.ts in the xmtp-agent-examples repo. For example:

 
yarn revoke <inbox-id> <installations-to-exclude>