Quick Start
This is your first step. Run an ErisPulse robot from scratch in 5 minutes—see the result first, then expand each step.
60-Second Demo: Let the Bot Reply to You First
1. Install (Python >= 3.10):
pip install ErisPulse
2. Initialize the project. The wizard will prompt you to set the project name, select the platform adapter to connect, and complete the configuration, then generate main.py and config/config.toml:
epsdk init
3. Open main.py, and replace it with these 9 lines of code:
from ErisPulse import sdk
from ErisPulse.Core.Event import command
@command("ping", help="Test if the bot is online")
async def ping_handler(event):
await event.reply("Pong! The bot is running normally.")
if __name__ == "__main__":
import asyncio
asyncio.run(sdk.run(keep_running=True))
4. Run:
epsdk run main.py
The terminal will output framework startup logs and adapter connection information. At this point, send /ping to the bot in your connected platform; it will reply:
Pong! The bot is running normally.
Seeing this reply confirms that the framework, adapter, and event handling chain are all working. If it doesn't work, go directly to the Troubleshooting section at the end of the document; if it works, continue reading to see what other options are available at each step.
Install ErisPulse: Three Ways
The above uses the most direct pip method. Choose according to your environment:
Install with pip
Ensure your Python version is >= 3.10, then install using pip:
pip install ErisPulse
If you have already installed uv, you can also use uv pip install ErisPulse for faster installation.
When you only want to install the epsdk command-line tool globally without polluting the project environment, it is recommended to use uv tool install:
uv tool install ErisPulse
After installation, epsdk will be globally available: when running within a project directory, it will automatically detect the project's .venv (installing epsdk install into the project environment, and running epsdk run using the project environment), while the framework itself is provided by the tool environment. See Installation Reference for details.
One-Click Installation Script (Recommended for New Environments)
The installation script will automatically detect your environment (Docker, Python, uv), and guide you to select the most suitable installation method, supporting multiple languages (Chinese/English/Japanese/Russian/Traditional Chinese).
Windows (PowerShell):
irm https://get.erisdev.com/install.ps1 -OutFile install.ps1; powershell -ExecutionPolicy Bypass -File install.ps1
macOS / Linux:
curl -fsSL https://get.erisdev.com/install.sh -o install.sh && chmod +x install.sh && ./install.sh
The script will guide you through:
- Docker Installation (recommended if Docker is detected): Choose image source (Docker Hub / GHCR), version channel (stable / pre-release), Dashboard management panel configuration, and port settings
- Global CLI Installation (uv tool, recommended): Install
epsdkas a global command, without virtual environments; uv automatically manages Python (even if the system version is too low); when running within a project directory, it automatically detects the project's.venv - Traditional Installation: Automatically create a virtual environment, select the ErisPulse version, and optionally install the Dashboard management panel module
Using Docker
The Docker image comes with the ErisPulse framework and the Dashboard management panel, supporting linux/amd64 and linux/arm64 architectures.
# Download docker-compose.yml
curl -O https://raw.githubusercontent.com/ErisPulse/ErisPulse/main/docker-compose.yml
# Set the Dashboard token and start
ERISPULSE_DASHBOARD_TOKEN=your-token docker compose up -d
Is Docker Hub unavailable?
Use the GitHub Container Registry image, and modify the image in docker-compose.yml:
image: ghcr.io/erispulse/erispulse:latest
After starting, access http://<host>:8000/Dashboard and log in using the set token.
Initialize Project
Interactive Initialization (Recommended)
epsdk init
This will start an interactive wizard that guides you through:
- Project name setting
- Log level configuration
- Server configuration (host and port)
- Adapter selection and configuration
- Project structure creation
Quick Initialization
# Quick mode with a specified project name
epsdk init -q -n my_bot
# Or just specify the project name
epsdk init -n my_bot
Manual Project Creation
If you prefer to create the project manually:
mkdir my_bot && cd my_bot
epsdk init
Installing Modules
Installing via CLI
epsdk install Yunhu AIChat
Viewing Available Modules
epsdk list-remote
Interactive Installation
Without specifying a package name, enter the interactive installation interface:
epsdk install
Running the Project
# Run normally
epsdk run main.py
# Hot reload mode (recommended for development)
epsdk run main.py --reload
Enable IDE Completion (Optional)
ErisPulse dynamically discovers modules/adapters, and IDEs cannot complete platform-specific methods by default.
Run the following command to generate type stubs:
epsdk types
After generation, use the imported types as variable annotations to obtain precise completion (see IDE Completion Guide):
from _ep_types import Yunhu
from ErisPulse import sdk
adapter: Yunhu = sdk.adapter.get("yunhu")
await adapter.Send.To("group", "123").Board(...) # Completion for platform-specific methods
Project Structure
After initialization, the project structure is as follows:
my_bot/
├── config/
│ └── config.toml # Configuration file
└── main.py # Entry file
Configuration File
Basic config.toml configuration:
[ErisPulse.server]
host = "0.0.0.0"
port = 8000
[ErisPulse.logger]
level = "INFO"
[Yunhu_Adapter]
# Adapter configuration
Next Steps
After the bot is running, choose your path based on your goals:
Want to build a group bot (handle messages, group management, notifications)
- Event Handling Introduction — How to write message, notification, and request events
- Common Tasks Examples — Storage, scheduled tasks, permission control
Want to write your own module / adapter
- Basic Concepts — First understand the design of adapters / modules / events
- Module Development Introduction
- Adapter Development Introduction
- Architecture Overview — Visual architecture diagram
Want to keep the bot running long-term
Encountered problems
- Create Your First Bot — Step-by-step guide to creating your first bot
- Startup Process and Manual Control — Diagnosing module / adapter loading failures
- CLI Command Reference — All
epsdksubcommands