Configuration Reference
This document was written by AI and has been manually reviewed.
Configuration Reference#
Config file formats#
NextBridge supports JSON, YAML, and TOML config files. Place the file in the data directory (default: data/). The first file found in this order is used:
config.json
config.yaml / config.yml
config.toml
Converting between formats#
Use the built-in convert command to translate between formats:
uv run main.py convert data/config.json data/config.yaml
uv run main.py convert data/config.yaml data/config.tomlStructure#
The config has a two-level structure regardless of format:
{
"global": {
// ... global config ...
},
"<platform>": {
"<instance_id>": {
// ... driver config ...
}
}
}| global | Global configuration options that apply to all drivers unless overridden |
| <platform> | One of napcat, discord, telegram, feishu, dingtalk, yunhu, kook, vocechat, matrix, signal, teams, googlechat, slack, mattermost, rocketchat, webhook |
| <instance_id> | A name you choose freely — used to reference this instance in rules |
Global Configuration#
The global section contains configuration options that apply to all drivers unless overridden in the driver-specific configuration.
| proxy | No | — | Global proxy URL for all drivers that support proxy configuration (e.g., http://proxy.example.com:8080). Individual driver proxy settings will override this global setting. |
| strict_echo_match | No | false | Controls how NextBridge prevents echoing messages back to the same channel/instance. When false (default), skips if target_id == msg.instance_id OR target_channel == msg.channel. When true, skips only if target_id == msg.instance_id AND target_channel == msg.channel. Default is false to maximize echo prevention. |
| log | No | — | Logging configuration for controlling log output and rotation. See Logging Configuration below. |
| database | No | — | Database configuration for storing message and user mappings. See Database Configuration below. |
{
"global": {
"proxy": "http://proxy.example.com:8080"
}
}If not set, the program will attempt to read proxy configuration from environment variables http_proxy, https_proxy, and all_proxy (case-insensitive). You can disable the use of system proxy by setting proxy to the special value disabled.
Logging Configuration#
NextBridge uses loguru for logging, which supports flexible log output and rotation. The logging configuration controls both console output and file logging behavior.
Configuration Options#
| log.level | No | INFO | Console log verbosity level. |
| log.file_level | No | DEBUG | File log verbosity level. Default is DEBUG for verbose output during troubleshooting. |
| log.dir | No | null | Directory path for log files. If null or not specified, file logging is disabled. Log files are automatically created with timestamp-based names in the specified directory. |
| log.rotation_size | No | 100 MB | Maximum size of a single log file before rotation (e.g., "100 MB", "500 MB"). Log files are automatically rotated when they exceed this size. |
| log.retention_days | No | 7 | Number of days to keep log files. Older log files are automatically deleted. Set to 0 to disable automatic deletion. |
| log.compression | No | zip | Compression format for rotated log files (e.g., "zip", "gz", "tar.gz"). Set to null to disable compression. |
Configuration Examples#
Basic logging (console only):
{
"global": {
"log": {
"level": "INFO"
}
}
}File logging with rotation:
{
"global": {
"log": {
"level": "INFO",
"dir": "logs",
"rotation_size": "100 MB",
"retention_days": 7,
"compression": "zip"
}
}
}Verbose logging for debugging:
{
"global": {
"log": {
"level": "DEBUG",
"dir": "logs",
"rotation_size": "50 MB",
"retention_days": 3,
"compression": null
}
}
}When log.dir is set, log files are automatically rotated when they exceed log.rotation_size. Old log files are automatically deleted after log.retention_days days. Rotated files can be compressed using log.compression to save disk space.
Database Configuration#
NextBridge uses SQLAlchemy for database operations, which supports multiple database backends including SQLite, MySQL, PostgreSQL, and more. The database is used to store:
Message ID mappings between different platforms
User bindings for cross-platform user identification
User display name mappings
Temporary binding codes
Configuration Options#
| database.url | No | sqlite:///messages.db | SQLAlchemy database URL. Relative SQLite paths are resolved under the data/ directory. |
| database.echo | No | false | Enable SQLAlchemy query logging for debugging. |
| database.pool_size | No | — | Connection pool size for non-SQLite databases. Uses SQLAlchemy default if not specified. |
| database.max_overflow | No | — | Maximum overflow size of the pool for non-SQLite databases. Uses SQLAlchemy default if not specified. |
| database.pool_recycle | No | 3600 | Recycle connections after this many seconds (default: 1 hour). |
Database URL Examples#
SQLite (default):
{
"global": {
"database": {
"url": "sqlite:///messages.db"
}
}
}MySQL:
{
"global": {
"database": {
"url": "mysql+pymysql://user:password@localhost:3306/nextbridge",
"pool_size": 10,
"max_overflow": 20,
"pool_recycle": 3600
}
}
}PostgreSQL:
{
"global": {
"database": {
"url": "postgresql://user:password@localhost:5432/nextbridge",
"pool_size": 10,
"max_overflow": 20,
"pool_recycle": 3600
}
}
}When using SQLite with a relative path (e.g., sqlite:///messages.db), the path is resolved relative to the data directory (data/). Absolute paths (e.g., sqlite:////var/lib/nextbridge/messages.db) are used as-is.
Connection pool settings (pool_size, max_overflow, pool_recycle) only apply to non-SQLite databases. SQLite uses a file-based storage and doesn’t support connection pooling in the same way.
You can run multiple instances of the same platform by adding more keys under the platform:
{
"discord": {
"server_a": { "bot_token": "...", "webhook_url": "..." },
"server_b": { "bot_token": "...", "webhook_url": "..." }
}
}Full example (JSON)#
{
"napcat": {
"qq_main": {
"ws_url": "ws://127.0.0.1:3001",
"ws_token": "secret"
}
},
"discord": {
"dc_main": {
"send_method": "webhook",
"webhook_url": "https://discord.com/api/webhooks/ID/TOKEN",
"bot_token": "BOT_TOKEN",
"max_file_size": 8388608
}
},
"telegram": {
"tg_main": {
"bot_token": "123456:ABC-DEF",
"max_file_size": 52428800
}
},
"feishu": {
"fs_main": {
"app_id": "cli_xxxx",
"app_secret": "xxxx",
"verification_token": "xxxx",
"encrypt_key": "",
"listen_port": 8080,
"listen_path": "/event"
}
},
"dingtalk": {
"dt_main": {
"app_key": "dingxxxx",
"app_secret": "xxxx",
"robot_code": "xxxx",
"signing_secret": "xxxx",
"listen_port": 8082,
"listen_path": "/dingtalk/event"
}
},
"matrix": {
"mx_main": {
"homeserver": "https://matrix.org",
"user_id": "@mybot:matrix.org",
"password": "your_password"
}
},
"signal": {
"sg_main": {
"api_url": "http://localhost:8080",
"number": "+12025551234"
}
},
"slack": {
"sl_main": {
"bot_token": "xoxb-...",
"app_token": "xapp-..."
}
}
}Full example (YAML)#
napcat:
qq_main:
ws_url: ws://127.0.0.1:3001
ws_token: secret
discord:
dc_main:
send_method: webhook
webhook_url: https://discord.com/api/webhooks/ID/TOKEN
bot_token: BOT_TOKEN
max_file_size: 8388608
matrix:
mx_main:
homeserver: https://matrix.org
user_id: "@mybot:matrix.org"
password: your_passwordFor per-driver config keys, see the individual driver pages in the Drivers section.