Deploy an agent

Deploy the agent on a Node.js host that supports environment variables and persistent storage.

Configuration

Variable	Purpose
`XMTP_BACKEND_URL`	Self-hosted backend URL, including scheme
`XMTP_WALLET_KEY`	Agent wallet key in `0x` hex format
`XMTP_DB_ENCRYPTION_KEY`	Optional 32-byte local database encryption key
`XMTP_DB_DIRECTORY`	Optional persistent root for databases and attachments
`XMTP_ENV`	Optional storage directory label; it does not select a backend

Agent.createFromEnv() creates a missing XMTP_DB_DIRECTORY with owner-only permissions where supported and stores the database below it. Mount this directory on a persistent volume. If this directory contains a legacy xmtp-<inbox-id>.db3 file for the signer, the Agent opens it in place. Without XMTP_DB_DIRECTORY, it checks the working directory for a legacy xmtp-<env>-<inbox-id>.db3 file for the signer. Set XMTP_ENV to select the storage label. Files for other inboxes do not block startup. If several files match the signer, set an explicit storage.location with dbPath and attachmentsDir.

Without a legacy database, the storage root is XMTP_DB_DIRECTORY or ./xmtp. A non-empty XMTP_ENV adds one directory below that root. Each inbox then uses {root}/{label}/{deployment}/{inbox-id}/xmtp.db3, with the label omitted when it is empty. The deployment directory includes a sanitized deployment identifier and its hash. Attachments are in the attachments directory next to the database.

Persist the whole storage root. It contains the database, SQLite sidecar files, attachments, and the backend deployment record. Use a consistent database backup or stop the client before you copy live SQLite files. Keep the same encryption key when you open an encrypted database again. If you omit the key, the SDK creates an unencrypted database.

For a host that supplies a persistent volume path, pass that path as a storage directory:

const 
const agent: Agent<unknown>
agent = await 
class Agent<ContentTypes = unknown>
Event-driven XMTP agent that routes conversations and messages to middleware.
Agent.
Agent<ContentTypes = unknown>.createFromEnv<[]>(options?: Partial<AgentCreateOptions<[]>> | undefined): Promise<Agent<unknown>>
Create an agent from XMTP_* variables. XMTP_BACKEND_URL overrides options.backend; one must be supplied. Pass backend.credentials in options for backend authentication.
createFromEnv({
  
storage?: StorageOptions | undefined
storage: {
    
location: StorageLocation
location: {
      
directory: string
directory: 
var process: NodeJS.Process
process.
NodeJS.Process.env: NodeJS.ProcessEnv
The process.env property returns an object containing the user environment.
See environ(7).
An example of this object looks like:
{
  "TERM": "xterm-256color",
  "SHELL": "/usr/local/bin/bash",
  "USER": "maciej",
  "PATH": "~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin",
  "PWD": "/Users/maciej",
  "EDITOR": "vim",
  "SHLVL": "1",
  "HOME": "/Users/maciej",
  "LOGNAME": "maciej",
  "_": "/usr/local/bin/node"
}
It is possible to modify this object, but such modifications will not be
reflected outside the Node.js process, or (unless explicitly requested)
to other Worker threads.
In other words, the following example would not work:
Terminal window
node -e 'process.env.foo = "bar"' &#x26;&#x26; echo $foo
While the following will:
import { env } from 'node:process';

env.foo = 'bar';
console.log(env.foo);
Assigning a property on process.env will implicitly convert the value
to a string. This behavior is deprecated. Future versions of Node.js may
throw an error when the value is not a string, number, or boolean.
import { env } from 'node:process';

env.test = null;
console.log(env.test);
// => 'null'
env.test = undefined;
console.log(env.test);
// => 'undefined'
Use delete to delete a property from process.env.
import { env } from 'node:process';

env.TEST = 1;
delete env.TEST;
console.log(env.TEST);
// => undefined
On Windows operating systems, environment variables are case-insensitive.
import { env } from 'node:process';

env.TEST = 1;
console.log(env.test);
// => 1
Unless explicitly specified when creating a Worker instance,
each Worker thread has its own copy of process.env, based on its
parent thread's process.env, or whatever was specified as the env option
to the Worker constructor. Changes to process.env will not be visible
across Worker threads, and only the main thread can make changes that
are visible to the operating system or to native add-ons. On Windows, a copy of process.env on a Worker instance operates in a case-sensitive manner
unlike the main thread.
@since ― v0.1.27
env.
string | undefined
RAILWAY_VOLUME_MOUNT_PATH ?? "./agent-data",
    },
  },
});

Caller-supplied storage takes precedence over XMTP_DB_DIRECTORY and the legacy database search. If storage.encryptionKey is absent, createFromEnv() still reads XMTP_DB_ENCRYPTION_KEY. XMTP_BACKEND_URL, when set, overrides options.backend.url.

Security

For an agent to function—whether it’s answering questions, executing commands, or providing automated responses—it must be able to read the conversation to understand what’s being asked, and write messages to respond.

Like any other user, this means your agent holds the cryptographic keys required to decrypt and send messages in the conversation. As an agent developer, it’s important to uphold the security of these keys and messages.

Never expose private keys: Use environment variables.
Keep messages secure and private: Do not log messages in plaintext. Do not share messages with third parties.
Label agents clearly: Clearly identify your agent as an agent and don’t have an agent impersonate a human.