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

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
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. 
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 use .env files for your API key management and configuration. 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

​
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 AgentAdvanced 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 SwarmSwarm 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 IntegrationAgent 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 TemplateProduction-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

​
Next Steps

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