sidebar_position
12

💻 Local Development Guide

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

Prerequisites

You can develop either in a dev container or directly on your host machine.

Requirements:

# Required
Node.js (v23+; not required if using the dev container)
pnpm (not required if using the dev container)
Git

VS Code (mandatory for using the dev container or coding)
Docker (mandatory for using the dev container or database development)
CUDA Toolkit (optional, for GPU acceleration)

Initial Setup

1. Repository Setup

Clone the repository and navigate to the project directory:

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

2. (Optional) Run Inside a Dev Container

Open the project directory in VS Code:
```
code .
```
In the bottom-right corner, you'll see a popup: "Reopen in Container" – Click it.
- If you don't see the popup or miss it, press F1, type: "Reopen in Container", and select it.
Wait for the container to initialize.
Open a terminal (hotkey: `Ctrl+Shift+``) and run commands from the container terminal going forward.

3. Setup dependencies

# Install dependencies
pnpm install

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

4. 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

5. 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

Direct Client Chat UI

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

# Open a 2nd terminal and start the client
pnpm start:client

NOTE: If you are using devcontainer, add --host argument to client:

pnpm start:client --host

NOTE: If you have run the server locally, but using a different port number:

SERVER_PORT="4567" pnpm start:client

NOTE: If you have hosted the server on a different computer/ domain, specify its base URL:

SERVER_BASE_URL="https://foobar.my.custom.domain:80" pnpm start:client

Look for the message: ➜ Local: http://localhost:5173/ Click on that link or open a browser window to that location. Once you do that you should see the chat interface connect with the system and you can start interacting with your character.

Database Development

SQLite (Recommended for Development)

import { SqliteDatabaseAdapter } from "@elizaos/core/adapters";
import Database from "better-sqlite3";

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

In-Memory Database (for Testing)

import { SqlJsDatabaseAdapter } from "@elizaos/core/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 "@elizaos/core/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 "@elizaos/core/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

Enable Debug Logging

# Add to your .env file
DEBUG=eliza:*

Use Debug Points

const debug = require("debug")("eliza:dev");

debug("Operation details: %O", {
    operation: "functionName",
    params: parameters,
    result: result,
});

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:

Install CUDA Toolkit with cuDNN and cuBLAS
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

Model Loading Issues

# Clear model cache
rm -rf ./models/*
# Restart with fresh download

Database Connection Issues

# Test database connection
pnpm run test:db-connection

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

Code Organization
- Place custom actions in custom_actions/
- Keep character files in characters/
- Store test data in tests/fixtures/
Testing Strategy
- Write unit tests for new features
- Use integration tests for plugins
- Test with multiple model providers
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

FAQ

Can I run multiple agents on one machine?

Yes, you can run multiple agents simultaneously:

Use different character files and configurations
Each agent needs unique credentials
Start with pnpm start --characters="characters/agent1.json,characters/agent2.json"
Configure different ports if needed

How do I customize a client/plugin package?

Copy the plugin into your eliza-start packages folder
Modify root package.json dependencies
Build the plugin
Follow standard plugin integration steps

Further Resources

Configuration Guide for setup details
Advanced Usage for complex features
Contributing Guide for contribution guidelines

Files

local-development.md

Latest commit

History