quickstart.mdx

title	Quickstart
description	Create and run your first elizaOS project.

Create an elizaOS project, install dependencies, and run it.

Create a project

npx elizaos create my-agent-app --template project
cd my-agent-app
bun install

You can also run elizaos create with no arguments for interactive template selection.

The `elizaos` CLI scaffolds and upgrades workspaces. After creation, use the generated project's scripts to run, build, and test the app.

Add environment variables

Copy the generated example file and add your model provider key:

cp .env.example .env

For an OpenAI-backed local setup:

OPENAI_API_KEY=your-api-key

Project templates may include additional app-specific .env.example files under apps/app/. Keep secrets in local .env files and out of version control.

Run the app

Start the generated development server:

bun run dev

The generated project owns the app runtime scripts. Common scripts include:

bun run dev
bun run build
bun run test
bun run typecheck
bun run lint

Open the URL printed by the dev server. In the default fullstack project, the branded app lives in apps/app, while the local elizaOS checkout lives under eliza/.

What was created

my-agent-app/
├── apps/
│   └── app/              # Project app: branded web, desktop, and mobile shell
├── eliza/                # Local elizaOS checkout used by the generated workspace
├── .elizaos/
│   └── template.json     # Template metadata for future upgrades
├── .env.example
├── package.json          # Project scripts
└── bunfig.toml

The project is the deployable product workspace. The project app is the branded shell inside apps/app. Runtime extensions are plugins, and app plugins are plugins that also contribute app surfaces.

Upgrade later

From the project root:

elizaos upgrade --check
elizaos upgrade

Use --check before writing changes. The upgrade command updates managed template files and reports conflicts instead of overwriting local edits.

Next steps

Update identity, bundle IDs, branding, app plugins, and platform config. Learn project, plugin, app plugin, project app, and Eliza Cloud app terminology. Build a reusable runtime extension. Review `create`, `upgrade`, `info`, and `version`.