AstrBot/docs/en/startup.md

Project Startup Guide

This document provides detailed instructions on how to start the AstrBot project, including initialization steps and configuration.

Requirements

• Python 3.10 - 3.13
• uv package manager (recommended)

Installation

Method 1: One-Click Installation with uv (Recommended)

# Install AstrBot
uv tool install astrbot

# Initialize the project (first time only)
astrbot init

# Start the project
astrbot run

Method 2: Development Mode Installation

# Clone the project
git clone https://github.com/AstrBotDevs/AstrBot
cd AstrBot

# Install development version
uv tool install git+https://github.com/AstrBotDevs/AstrBot@dev

# Initialize
astrbot init

# Start
astrbot run

Method 3: Run from Source

git clone https://github.com/AstrBotDevs/AstrBot
cd AstrBot

# Create virtual environment
uv venv --seed
source .venv/bin/activate  # Linux/macOS
# or: .venv\Scripts\activate  # Windows

# Install dependencies
uv pip install -e .

# Initialize
astrbot init

# Start
astrbot run

Initialization Details

The astrbot init command performs the following operations:

1. Creates .astrbot marker file - Identifies the AstrBot root directory
2. Creates data directory structure:
   • data/ - Main data directory
   • data/config/ - Configuration files
   • data/plugins/ - Plugins directory
   • data/temp/ - Temporary files directory
   • data/skills/ - Skills directory
3. Generates configuration file data/cmd_config.json
4. Generates environment file .env (from config.template)
5. Installs Dashboard (optional, not recommended for server mode)

Initialization Options

Option	Description
-y, --yes	Skip confirmation prompts
-b, --backend-only	Initialize backend only, skip Dashboard
-u, --admin-username	Set Dashboard admin username
--root	Specify AstrBot root directory

Startup Details

The astrbot run command starts the AstrBot service.

Startup Options

Option	Description
-H, --host	Dashboard bind address
-p, --port	Dashboard bind port
-r, --reload	Enable plugin auto-reload
-b, --backend-only	Start backend only, skip WebUI
-l, --log-level	Log level (DEBUG, INFO, WARNING, ERROR)
--ssl-cert	SSL certificate path
--ssl-key	SSL private key path
--ssl-ca	SSL CA certificate path
--debug	Debug mode
-c, --service-config	Service configuration file path

Startup Output

Upon successful startup:

AstrBot is running...
Visit the dashboard at : https://dash.astrbot.men/
Backend Requests : localhost or based on https

Environment Variables

Core Configuration

Variable	Description	Default
ASTRBOT_ROOT	AstrBot root directory	Auto-detected
ASTRBOT_LOG_LEVEL	Log level	INFO
ASTRBOT_RELOAD	Enable plugin hot-reload	-
ASTRBOT_DISABLE_METRICS	Disable metrics upload	-

Dashboard Configuration

Variable	Description	Default
ASTRBOT_DASHBOARD_ENABLE	Enable Dashboard	True
ASTRBOT_HOST	Dashboard bind address	0.0.0.0
ASTRBOT_PORT	Dashboard bind port	8000

SSL Configuration

Variable	Description
ASTRBOT_SSL_ENABLE	Enable SSL
ASTRBOT_SSL_CERT	SSL certificate path
ASTRBOT_SSL_KEY	SSL private key path
ASTRBOT_SSL_CA_CERTS	CA certificate path

Proxy Configuration

Variable	Description
http_proxy	HTTP proxy address
https_proxy	HTTPS proxy address
no_proxy	Addresses to bypass proxy

Platform Integration

Variable	Description
DASHSCOPE_API_KEY	Alibaba DashScope API Key (for Rerank)
COZE_API_KEY	Coze API Key
COZE_BOT_ID	Coze Bot ID
BAY_DATA_DIR	Computer Use data directory

Directory Structure

AstrBot/
├── .astrbot              # AstrBot root marker
├── .env                  # Environment configuration
├── data/                 # Data directory
│   ├── config/
│   │   └── cmd_config.json  # Main configuration file
│   ├── plugins/          # Plugins directory
│   ├── skills/          # Skills directory
│   └── temp/            # Temporary files directory
├── astrbot/             # Core code
│   ├── cli/             # Command line tool
│   ├── core/            # Core modules
│   ├── dashboard/       # Dashboard frontend
│   └── ...
└── ...

Configuration File

The main configuration file is located at data/cmd_config.json, containing:

• LLM provider configuration
• Platform adapter configuration
• Plugin settings
• Dashboard settings
• Proxy settings

Troubleshooting

Port Already in Use

If the port is already in use:

# Check process using the port
lsof -i :8000

# Or start on a different port
astrbot run --port 8080

Multiple Instance Conflict

AstrBot uses a lock file mechanism to prevent multiple instances. To force start:

# Remove lock file
rm astrbot.lock

# Restart
astrbot run

Dashboard Not Accessible

1. Verify ASTRBOT_DASHBOARD_ENABLE is True
2. Check firewall settings
3. Confirm port is not blocked

Viewing Logs

# Start with debug mode for detailed logs
astrbot run --debug --log-level DEBUG

Next Steps

• Configure LLM Providers
• Install Plugins
• Use Skills
• Deploy to Server