Overview

Understanding and building with elizaOS projects

Projects are the primary deployable unit in elizaOS. Each project contains one or more agents, and plugins can be managed either at the agent level or shared across the project. A project is container template that you develop locally and ship to production.

What is a Project?

A project in elizaOS is your development workspace and deployment unit. It’s where you:

• Configure and run one or more agents
• Develop and test plugins
• Manage environment settings
• Build complete AI applications

Projects can include a fully customizable chat interface for user interaction, or run as headless services connecting to platforms like Discord or Twitter. The framework is flexible enough to support both frontend applications and background services.

Think of a project as a TypeScript application that orchestrates agents. Each agent can have unique plugins, creating specialized capabilities within your application.

Development Pattern

The elizaOS development workflow centers around projects:

1. Create a project

   Initialize your development workspace with elizaos create --type project

2. Configure agents

   Define agent personalities and select plugins

3. Develop features

   Build custom plugins and actions within the project context

4. Test locally

   Run and test using elizaos start without needing the full monorepo

5. Deploy to production

   Ship the complete project as your production application

This pattern gives you access to all elizaOS core features without managing the entire framework codebase.

Project Structure

Standard Project

my-project/
├── src/                 # Source code (you edit these)
│   ├── index.ts         # Project entry point
│   ├── character.ts     # Default Eliza character
│   ├── __tests__/       # Test files (E2E and component)
│   ├── frontend/        # Frontend components (if using web UI)
│   └── plugins/         # Custom plugins (optional)
├── .env                 # Environment variables
├── package.json         # Dependencies
├── tsconfig.json        # TypeScript config
├── bun.lock            # Lock file
│
├── dist/                # 🔨 Built/compiled output
├── node_modules/        # 📦 Installed dependencies  
├── .eliza/              # 💾 Local runtime data
└── scripts/             # 🛠️ Utility scripts

src/ - Your main development workspace

Your code lives here: This is your main entry point area to build your agents and logic.

You can organize this however works for your project - there are some common patterns, but it’s flexible. All your TypeScript source code and configurations go here.

This is committed to version control and where you’ll spend most of your dev time.

dist/ - Compiled JavaScript output

Created by: elizaos start or elizaos dev (automatic), or manually with bun run build

Contains the compiled JavaScript files from your TypeScript source. This is what actually runs when you start your project.

• Safe to delete (will be regenerated automatically)
• Not committed to version control

node_modules/ - Installed dependencies

Created by: bun install or npm install

Contains all the packages your project depends on, including elizaOS core and plugins.

• Safe to delete (reinstall with bun install)
• Not committed to version control
• Managed by your package manager

.eliza/ - Local runtime data

Created by: Running your agent

Stores local runtime data including:

• PGLite database files (if using local DB)
• Cache files
• Temporary agent state
• Plugin data storage

Safe to delete to reset your local development state.

scripts/ - Utility scripts

Created by: Project template or manually

Contains helpful scripts for development:

• Test utilities
• Database migrations
• Deployment scripts
• Custom build steps
• Is committed to version control, but generally not used much during dev process

Clean Slate: Run rm -rf node_modules dist .eliza to completely reset your project’s generated files. Then bun install and your next elizaos start will rebuild automatically.

Project Definition

Projects are flexible containers you can design to fit your use case. The default entry point for every project is src/index.ts, where you define your agents, their character files, and any custom plugins or services. You might configure a single agent with specialized plugins, or coordinate multiple agents with distinct personalities and capabilities.

Build your project structure to match your needs and goals, whether that’s organizing agents by function, separating character configurations, or creating shared utilities. The elizaOS runtime will orchestrate everything once you define your project configuration.

src/index.ts (Single Agent)

import { Project, ProjectAgent, IAgentRuntime } from '@elizaos/core';
import { character } from './character';

export const projectAgent: ProjectAgent = {
  character,
  init: async (runtime: IAgentRuntime) => {
    console.log(`Initializing ${character.name}`);
    // Optional: Setup knowledge base, connections, etc.
  },
  // plugins: [customPlugin], // Project-specific plugins
};

const project: Project = {
  agents: [projectAgent],
};

export default project;

Environment Configuration

Projects come with .env files for API keys and configuration, plus .env.example with additional variables you can copy. Define these at the project level to start, then you can define them at the agent level in multi-agent projects using the secrets array in your character .ts/.json object.

.env

# Model Providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Platform Integrations  
DISCORD_API_TOKEN=...
TELEGRAM_BOT_TOKEN=...
TWITTER_API_KEY=...

# Database
DATABASE_URL=postgresql://localhost/eliza
PGLITE_DIR=./tmp/pglite

# Settings
LOG_LEVEL=info
NODE_ENV=production

For detailed information about server security, authentication, and UI configuration environment variables, see the Environment Variables documentation.

Running Projects Locally

Start your project with the elizaOS CLI:

# Start your project
elizaos start

# Development mode with hot reload
elizaos dev

# Start with specific character
elizaos start --character ./custom-character.ts

See the CLI Reference for all available options and flags.

Advanced Project Examples

Explore these real-world projects showcasing different elizaOS capabilities:

Spartan

Onchain Trading Agent

Advanced capabilities for blockchain trading:

• Multi-modal reasoning across data types
• Strategic decision-making framework
• Long-term memory with retrieval strategies
• Complex action chaining
• Advanced prompt engineering

The Org

Business Profiles Swarm

Swarm of business profiles who collaborate and work together:

• Executive, department, and operational layers
• Inter-agent communication protocols
• Specialized role-based expertise
• Coordinated decision-making
• Shared knowledge management

3D Hyperfy Starter

3D World Integration

Agent that connects to 3D virtual worlds:

• WebSocket connection to Hyperfy worlds
• Voice chat support (ElevenLabs/OpenAI)
• Screen perception capabilities
• 3D MMO development prototyping
• Real-time interaction in virtual spaces

Next.js Starter

Web Application Template

Production-ready web interface for agents:

• Real-time chat with Socket.IO
• Document management system
• Automatic API proxying
• Debug panel for development
• Ready for Vercel/Netlify deployment

Want more inspiration? Check out What You Can Build to see other agents you can create: trading bots, content creators, business automation, virtual NPCs, and more.

Testing Projects

Projects include comprehensive testing capabilities:

# Run all tests
elizaos test

# Component tests only
elizaos test --type component

# End-to-end tests
elizaos test --type e2e

# Filter by test name
elizaos test --name "character configuration"

See the Test a Project guide for comprehensive testing strategies.

Deployment Options

Projects come ready to be deployed out of the box. They include Dockerfiles so you can deploy using containers, or you can easily push your project to GitHub and use a managed cloud service.

See the Deploy a Project guide for detailed instructions on all deployment methods.

FAQ

What's the difference between an agent, a plugin, and a project?

Agent: A single AI personality with specific capabilities defined by its character configuration and plugins.

Plugin: A reusable module that adds specific capabilities (like Twitter integration, web search, or trading features) to agents.

Project: The container application that runs one or more agents. It’s your development workspace and what you deploy to production.

Key relationships:

• A project has one or many agents
• Agents import/use plugins via their character configuration
• Plugins are reusable across projects and agents
• You can’t have a project within a project or a project within a plugin
• Projects are the top-level containers for agents and plugins
• Plugin configuration can be defined at the project level (API keys in project .env) or agent-specific (in the character’s secrets array)

Think of it this way: Agents are the “who” (personalities), Plugins are the “what” (capabilities), Projects are the “where” (application container).

Can I develop plugins within a project?

Yes! You can create custom plugins in your project’s src/plugins/ directory and test them locally.

You can also develop a standalone plugin with elizaos create --type plugin. If you run elizaos dev from that plugin directory, it will spin up with a test agent. But ultimately, everyone will want to add that plugin to a project at some point.

See the Create a Plugin guide for details.

Do I need the entire elizaOS monorepo to develop?

No! That’s the beauty of projects. When you create a project with elizaos create, you get a standalone workspace with just what you need. The CLI and core packages provide all the framework functionality without the monorepo complexity.

How do agents communicate in multi-agent projects?

Agents in the same project can communicate through:

• Shared memory systems
• Message passing via the runtime
• Event-driven coordination
• Shared service instances

See the Add Multiple Agents guide for patterns.

Can different agents use different model providers?

Yes! Each agent can configure its own model provider through settings:

settings: {
  modelProvider: 'anthropic', // or 'openai', 'llama', etc.
}

What's the best way to deploy my project?

It depends on what you’re comfortable with. We support managed cloud, Docker, bare metal, whatever you like.

See the Deploy a Project guide for detailed information on all deployment options.

See Also

Quickstart

Get started in under 5 minutes

Customize an Agent

Learn to configure agent personalities

CLI Reference

Complete command reference

API Reference

REST API documentation