Skip to main content

💻 Local Development Guide

This guide covers setting up and working with Eliza in a development environment.

Prerequisites

Before you begin, ensure you have:

# Required
Node.js 22+
pnpm
Git

# Optional but recommended
VS Code
Docker (for database development)
CUDA Toolkit (for GPU acceleration)

Initial Setup

1. Repository Setup

# Clone the repository
git clone https://github.com/ai16z/eliza.git
cd eliza

# Install dependencies
pnpm install

# Install optional dependencies
pnpm install --include=optional sharp

2. Environment Configuration

Create your development environment file:

cp .env.example .env

Configure essential development variables:

# Minimum required for local development
OPENAI_API_KEY=sk-* # Optional, for OpenAI features
X_SERVER_URL= # Leave blank for local inference
XAI_API_KEY= # Leave blank for local inference
XAI_MODEL=meta-llama/Llama-3.1-7b-instruct # Local model

3. Local Model Setup

For local inference without API dependencies:

# Install CUDA support for NVIDIA GPUs
npx --no node-llama-cpp source download --gpu cuda

# The system will automatically download models from
# Hugging Face on first run

Development Workflow

Running the Development Server

# Start with default character
pnpm run dev

# Start with specific character
pnpm run dev --characters="characters/my-character.json"

# Start with multiple characters
pnpm run dev --characters="characters/char1.json,characters/char2.json"

Development Commands

pnpm run build          # Build the project
pnpm run clean # Clean build artifacts
pnpm run dev # Start development server
pnpm run test # Run tests
pnpm run test:watch # Run tests in watch mode
pnpm run lint # Lint code

Database Development

import { SqliteDatabaseAdapter } from "@ai16z/eliza/adapters";
import Database from "better-sqlite3";

const db = new SqliteDatabaseAdapter(new Database("./dev.db"));

In-Memory Database (for Testing)

import { SqlJsDatabaseAdapter } from "@ai16z/eliza/adapters";

const db = new SqlJsDatabaseAdapter(new Database(":memory:"));

Schema Management

# Create new migration
pnpm run migration:create

# Run migrations
pnpm run migration:up

# Rollback migrations
pnpm run migration:down

Testing

Running Tests

# Run all tests
pnpm test

# Run specific test file
pnpm test tests/specific.test.ts

# Run tests with coverage
pnpm test:coverage

# Run database-specific tests
pnpm test:sqlite
pnpm test:sqljs

Writing Tests

import { runAiTest } from "@ai16z/eliza/test_resources";

describe("Feature Test", () => {
beforeEach(async () => {
// Setup test environment
});

it("should perform expected behavior", async () => {
const result = await runAiTest({
messages: [
{
user: "user1",
content: { text: "test message" },
},
],
expected: "expected response",
});
expect(result.success).toBe(true);
});
});

Plugin Development

Creating a New Plugin

// plugins/my-plugin/src/index.ts
import { Plugin } from "@ai16z/eliza/types";

export const myPlugin: Plugin = {
name: "my-plugin",
description: "My custom plugin",
actions: [],
evaluators: [],
providers: [],
};

Custom Action Development

// plugins/my-plugin/src/actions/myAction.ts
export const myAction: Action = {
name: "MY_ACTION",
similes: ["SIMILAR_ACTION"],
validate: async (runtime: IAgentRuntime, message: Memory) => {
return true;
},
handler: async (runtime: IAgentRuntime, message: Memory) => {
// Implementation
return true;
},
examples: [],
};

Debugging

VS Code Configuration

Create .vscode/launch.json:

{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Debug Eliza",
"skipFiles": ["<node_internals>/**"],
"program": "${workspaceFolder}/src/index.ts",
"runtimeArgs": ["-r", "ts-node/register"],
"env": {
"DEBUG": "eliza:*"
}
}
]
}

Debugging Tips

  1. Enable Debug Logging
# Add to your .env file
DEBUG=eliza:*
  1. Use Debug Points
const debug = require("debug")("eliza:dev");

debug("Operation details: %O", {
operation: "functionName",
params: parameters,
result: result,
});
  1. Memory Debugging
# Increase Node.js memory for development
NODE_OPTIONS="--max-old-space-size=8192" pnpm run dev

Common Development Tasks

1. Adding a New Character

{
"name": "DevBot",
"description": "Development testing bot",
"modelProvider": "openai",
"settings": {
"debug": true,
"logLevel": "debug"
}
}

2. Creating Custom Services

class CustomService extends Service {
static serviceType = ServiceType.CUSTOM;

async initialize() {
// Setup code
}

async process(input: any): Promise<any> {
// Service logic
}
}

3. Working with Models

// Local model configuration
const localModel = {
modelProvider: "llamalocal",
settings: {
modelPath: "./models/llama-7b.gguf",
contextSize: 8192,
},
};

// Cloud model configuration
const cloudModel = {
modelProvider: "openai",
settings: {
model: "gpt-4o-mini",
temperature: 0.7,
},
};

Performance Optimization

CUDA Setup

For NVIDIA GPU users:

  1. Install CUDA Toolkit with cuDNN and cuBLAS
  2. Set environment variables:
CUDA_PATH=/usr/local/cuda  # Windows: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.0

Memory Management

class MemoryManager {
private cache = new Map();
private maxSize = 1000;

async cleanup() {
if (this.cache.size > this.maxSize) {
// Implement cleanup logic
}
}
}

Troubleshooting

Common Issues

  1. Model Loading Issues
# Clear model cache
rm -rf ./models/*
# Restart with fresh download
  1. Database Connection Issues
# Test database connection
pnpm run test:db-connection
  1. Memory Issues
# Check memory usage
node --trace-gc index.js

Development Tools

# Generate TypeScript documentation
pnpm run docs:generate

# Check for circular dependencies
pnpm run madge

# Analyze bundle size
pnpm run analyze

Best Practices

  1. Code Organization

    • Place custom actions in custom_actions/
    • Keep character files in characters/
    • Store test data in tests/fixtures/
  2. Testing Strategy

    • Write unit tests for new features
    • Use integration tests for plugins
    • Test with multiple model providers
  3. Git Workflow

    • Create feature branches
    • Follow conventional commits
    • Keep PRs focused

Additional Tools

Character Development

# Generate character from Twitter data
npx tweets2character

# Convert documents to knowledge base
npx folder2knowledge <path/to/folder>

# Add knowledge to character
npx knowledge2character <character-file> <knowledge-file>

Development Scripts

# Analyze codebase
./scripts/analyze-codebase.ts

# Extract tweets for training
./scripts/extracttweets.js

# Clean build artifacts
./scripts/clean.sh

Further Resources