Quickstart Guide
Prerequisites
Before getting started with Eliza, ensure you have:
- Node.js 23+
- pnpm 9+
- Git for version control
- A code editor (VS Code or VSCodium recommended)
- CUDA Toolkit (optional, for GPU acceleration)
Installation
-
Clone and Install
Please be sure to check what the latest available stable version tag is.
Clone the repository
git clone https://github.com/ai16z/eliza.git
Enter directory
cd eliza
Switch to latest tagged release
# Checkout the latest release
# This project iterates fast, so we recommend checking out the latest release
git checkout $(git describe --tags --abbrev=0)Install dependencies (on initial run)
pnpm install --no-frozen-lockfile
Quickstart Guide Update
Important Note on pnpm Lockfile Management
By default, the pnpm
lockfile will not be updated during installations based off of .npmrc frozen-lockfile=true. To update the lockfile, you need to run the command:
pnpm install --no-frozen-lockfile
Please only use this command when you initially instantiating the repo or are bumping the version of a package or adding a new package to your package.json. This practice helps maintain consistency in your project's dependencies and prevents unintended changes to the lockfile.
Build the local libraries
pnpm build
-
Configure Environment
Copy example environment file
cp .env.example .env
Edit
.env
and add your values:# Suggested quickstart environment variables
DISCORD_APPLICATION_ID= # For Discord integration
DISCORD_API_TOKEN= # Bot token
HEURIST_API_KEY= # Heurist API key for LLM and image generation
OPENAI_API_KEY= # OpenAI API key
GROK_API_KEY= # Grok API key
ELEVENLABS_XI_API_KEY= # API key from elevenlabs (for voice)
Choose Your Model
Eliza supports multiple AI models:
- Heurist: Set
modelProvider: "heurist"
in your character file. Most models are uncensored. - Llama: Set
XAI_MODEL=meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo
- Grok: Set
XAI_MODEL=grok-beta
- OpenAI: Set
XAI_MODEL=gpt-4o-mini
orgpt-4o
You set which model to use inside the character JSON file
Local inference
For llama_local inference:
- Set
XAI_MODEL
to your chosen model - Leave
X_SERVER_URL
andXAI_API_KEY
blank - The system will automatically download the model from Hugging Face
LOCAL_LLAMA_PROVIDER
can be blank
Note: llama_local requires a GPU, it currently will not work with CPU inference
For Ollama inference:
- If
OLLAMA_SERVER_URL
is left blank, it defaults tolocalhost:11434
- If
OLLAMA_EMBEDDING_MODE
is left blank, it defaults tomxbai-embed-large
Create Your First Agent
-
Create a Character File
Check out
characters/trump.character.json
orcharacters/tate.character.json
as a template you can use to copy and customize your agent's personality and behavior. Additionally you can readcore/src/core/defaultCharacter.ts
(in 0.0.10 but post-refactor will be inpackages/core/src/defaultCharacter.ts
) -
Start the Agent
Inform it which character you want to run:
pnpm start --character="characters/trump.character.json"
You can also load multiple characters with the characters option with a comma separated list:
pnpm start --characters="characters/trump.character.json,characters/tate.character.json"
-
Interact with the Agent
Now you're ready to start a conversation with your agent! Open a new terminal window
pnpm start:client
Once the client is running, you'll see a message like this:
➜ Local: http://localhost:5173/
Simply click the link or open your browser to http://localhost:5173/
. You'll see the chat interface connect to the system, and you can begin interacting with your character.
Platform Integration
Discord Bot Setup
- Create a new application at Discord Developer Portal
- Create a bot and get your token
- Add bot to your server using OAuth2 URL generator
- Set
DISCORD_API_TOKEN
andDISCORD_APPLICATION_ID
in your.env
Twitter Integration
Add to your .env
:
TWITTER_USERNAME= # Account username
TWITTER_PASSWORD= # Account password
TWITTER_EMAIL= # Account email
TWITTER_COOKIES= # Account cookies (auth_token and CT0)
Example for TWITTER_COOKIES
The TWITTER_COOKIES variable should be a JSON string containing the necessary cookies. You can find these cookies in your web browser's developer tools. Here is an example format:
TWITTER_COOKIES='[{"key":"auth_token","value":"your token","domain":".twitter.com"},
{"key":"ct0","value":"your ct0","domain":".twitter.com"},
{"key":"guest_id","value":"your guest_id","domain":".twitter.com"}]'
Telegram Bot
- Create a bot
- Add your bot token to
.env
:
TELEGRAM_BOT_TOKEN=your_token_here
Optional: GPU Acceleration
If you have an NVIDIA GPU:
# Install CUDA support
npx --no node-llama-cpp source download --gpu cuda
# Ensure CUDA Toolkit, cuDNN, and cuBLAS are installed
Basic Usage Examples
Chat with Your Agent
# Start chat interface
pnpm start
Run Multiple Agents
pnpm start --characters="characters/trump.character.json,characters/tate.character.json"
Common Issues & Solutions
-
Node.js Version
- Ensure Node.js 23.3.0 is installed
- Use
node -v
to check version - Consider using nvm to manage Node versions
-
Sharp Installation If you see Sharp-related errors:
pnpm install --include=optional sharp
-
CUDA Setup
- Verify CUDA Toolkit installation
- Check GPU compatibility with toolkit
- Ensure proper environment variables are set
-
Exit Status 1 If you see
triggerUncaughtException(
^
[Object: null prototype] {
[Symbol(nodejs.util.inspect.custom)]: [Function: [nodejs.util.inspect.custom]]
}You can try these steps, which aim to add
@types/node
to various parts of the project# Add dependencies to workspace root
pnpm add -w -D ts-node typescript @types/node
# Add dependencies to the agent package specifically
pnpm add -D ts-node typescript @types/node --filter "@ai16z/agent"
# Also add to the core package since it's needed there too
pnpm add -D ts-node typescript @types/node --filter "@ai16z/eliza"
# First clean everything
pnpm clean
# Install all dependencies recursively
pnpm install -r
# Build the project
pnpm build
# Then try to start
pnpm start -
Better sqlite3 was compiled against a different Node.js version If you see
Error starting agents: Error: The module '.../eliza-agents/dv/eliza/node_modules/better-sqlite3/build/Release/better_sqlite3.node'
was compiled against a different Node.js version using
NODE_MODULE_VERSION 131. This version of Node.js requires
NODE_MODULE_VERSION 127. Please try re-compiling or re-installingYou can try this, which will attempt to rebuild better-sqlite3.
pnpm rebuild better-sqlite3
If that doesn't work, try clearing your node_modules in the root folder
rm -fr node_modules; pnpm store prune
Then reinstall the requirements
pnpm i
Next Steps
Once you have your agent running, explore:
For detailed API documentation, troubleshooting, and advanced features, check out our full documentation.
Join our Discord community for support and updates!