Using Hybrid

Master the Hybrid CLI and development workflow for building and managing your agents.

Key Management

Generating XMTP Keys

Create new keys for your agent:

npx hybrid keys

This generates:

• Wallet private key - For XMTP identity and signing
• XMTP DB encryption key - For message database encryption

Keys are displayed in the terminal. Save them to your .env file manually or use the --write flag:

Automatically Writing Keys to .env

npx hybrid keys --write

This automatically writes the keys to your .env file:

# Generated by hybrid keys --write
XMTP_WALLET_KEY=0x1234567890abcdef...
XMTP_DB_ENCRYPTION_KEY=abcdef1234567890...

Key Security Best Practices

• Store keys in environment variables
• Use different keys for development and production
• Keep backup copies in secure storage
• Add .env to your .gitignore

• Commit keys to version control
• Share keys in plain text
• Use the same keys across multiple agents
• Store keys in client-side code

Development Workflow

Development Server

Start your agent in development mode:

npx hybrid dev

Features:

• Hot reload - Automatic restart on code changes
• Debug logging - Detailed console output
• XMTP integration - Connects to XMTP network automatically

The dev server:

• Compiles TypeScript in watch mode
• Runs your agent
• Listens for XMTP messages
• Restarts on file changes

Building Projects

Build your TypeScript project:

npx hybrid build

This compiles your TypeScript code to JavaScript in the dist directory.

Project Cleanup

Clean build artifacts:

npx hybrid clean

Removes:

• dist directory
• Temporary build files

Framework Upgrades

Upgrade all Hybrid packages to the latest version:

npx hybrid upgrade

This will:

• Update all @hybrd/* and hybrid packages
• Check for latest versions
• Update your package.json

XMTP Network Operations

Wallet Registration

Register your agent's wallet with the XMTP production network:

npx hybrid register

This process:

1. Reads your XMTP_WALLET_KEY from environment
2. Creates an XMTP identity
3. Registers the wallet on the XMTP network
4. Confirms successful registration

Note: Registration is only needed for production. Development works without registration.

Revoking Installations

Remove specific XMTP installation by inbox ID:

npx hybrid revoke <inboxId>

Revoke all installations for your wallet:

npx hybrid revoke:all

Use cases:

• Security breach - Immediately revoke compromised installations
• Key rotation - Revoke old installations before using new keys
• Testing cleanup - Remove test installations

Available Commands

Alias Commands

You can use the shorter hy alias for all commands:

hy dev       # Same as: npx hybrid dev
hy keys      # Same as: npx hybrid keys
hy build     # Same as: npx hybrid build
hy up        # Same as: npx hybrid upgrade

Environment Variables

Required Environment Variables

# XMTP Configuration
XMTP_WALLET_KEY=0x...          # Required: Your XMTP wallet private key
XMTP_DB_ENCRYPTION_KEY=...     # Required: Database encryption key
 
# AI Provider
OPENROUTER_API_KEY=...         # Required: Your AI provider API key

Optional Environment Variables

# Server Configuration
PORT=8454                       # Optional: HTTP server port (default: 8454)
 
# XMTP Network
XMTP_ENV=production            # Optional: XMTP environment (default: production)
 
# Blockchain Tools (if using)
PRIVATE_KEY=0x...              # Optional: For sending transactions
RPC_URL=https://...            # Optional: Custom RPC endpoint

Development Best Practices

Project Structure

my-agent/
├── src/
│   └── agent.ts              # Your agent configuration
├── .env                      # Environment variables (not in git)
├── .gitignore               # Ignore .env and node_modules
├── package.json
└── tsconfig.json

Local Testing

1. Generate keys: npx hybrid keys --write
2. Add your API keys to .env
3. Start development: npx hybrid dev
4. Message your agent via XMTP (address shown in terminal)

Deployment

1. Build your project: npx hybrid build
2. Set environment variables in your hosting platform
3. Register wallet (production): npx hybrid register
4. Deploy to your hosting platform
5. Monitor logs for agent activity

Next Steps

• Learn about Agent Configuration for customizing behavior
• Explore Behaviors for message processing
• Check out Blockchain Tools for crypto functionality
• See XMTP Tools for messaging capabilities