Quickstart

Get up and running with Hybrid agents in minutes. This guide will take you through setup, configuration, and running your agent.

Setup & Installation

Create New Project

npm create hybrid

then, cd into the project directory and install dependencies:

cd my-agent
pnpm install # or yarn install or npm install

Generate Keys

Generate XMTP wallet and encryption keys:

npx hybrid keys

This generates:

Wallet private key - For XMTP identity
DB encryption key - For message encryption

Use the --write flag to automatically save keys to your .env file:

npx hybrid keys --write

Environment Setup

Configure your .env file:

# AI Provider Configuration (OpenRouter recommended)
OPENROUTER_API_KEY=your_openrouter_api_key
 
# XMTP Configuration (generated by hybrid keys)
XMTP_WALLET_KEY=0x1234...
XMTP_DB_ENCRYPTION_KEY=abc123...

Configure Your Agent

Basic Agent Configuration

Create your agent in src/agent.ts:

import { Agent } from "hybrid"
import { createOpenRouter } from "@openrouter/ai-sdk-provider"
 
const openrouter = createOpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY
})
 
const agent = new Agent({
  name: "My Agent",
  model: openrouter("x-ai/grok-4"),
  instructions: "You are a helpful AI agent that responds to messages."
})

Add Behaviors

Behaviors control message processing:

import { filterMessages, reactWith, threadedReply } from "hybrid/behaviors"
 
await agent.listen({
  port: process.env.PORT || "8454",
  behaviors: [
    // Only respond to replies, DMs, mentions, or specific reactions
    filterMessages((filters) => {
      return (
        filters.isReply() ||
        filters.isDM() ||
        filters.hasMention("@agent") ||
        filters.isReaction("👍")
      )
    }),
    
    // React to messages
    reactWith("👀"),
    
    // Always reply in threads
    threadedReply()
  ]
})

Add Tools (Optional)

Add blockchain tools to your agent. Note: XMTP tools are automatically included when your agent starts listening for messages.

import { blockchainTools } from "hybrid/tools"
 
const agent = new Agent({
  name: "My Agent",
  model: openrouter("x-ai/grok-4"),
  instructions: "You can check balances and send messages.",
  tools: blockchainTools,
  createRuntime: (runtime) => ({
    // Configure blockchain tools
    privateKey: process.env.PRIVATE_KEY,
    rpcUrl: process.env.RPC_URL,
    defaultChain: "mainnet"
  })
})

Start Development Server

npx hybrid dev

Your agent is now running and listening for XMTP messages on port 8454.

Deploy Your Agent

Build for Production

npx hybrid build

Deploy to Hosting Platform

Deploy to your preferred hosting platform:

# Example: Deploy to Railway, Render, or any Node.js host
# Make sure to set environment variables in your hosting platform

Register with XMTP Network (Production)

If deploying to production, register your wallet with XMTP:

npx hybrid register

Next Steps

Learn about Core Concepts to understand how Hybrid agents work
Explore Agent Configuration for customizing behavior
Check out XMTP Tools for messaging capabilities
Add Blockchain Tools for crypto functionality

Quick Reference

Command	Description
`npx hybrid keys`	Generate XMTP wallet and encryption keys
`npx hybrid keys --write`	Generate and save keys to .env
`npx hybrid dev`	Start development server with watch mode
`npx hybrid build`	Build the TypeScript project
`npx hybrid clean`	Remove dist directory
`npx hybrid register`	Register wallet with XMTP network
`npx hybrid revoke <inboxId>`	Revoke XMTP installation
`npx hybrid revoke:all`	Revoke all XMTP installations
`npx hybrid upgrade`	Upgrade all hybrid packages