Installation and Deployment

# Download

Download the binary file for your platform from Github Releases (opens new window).

# Start

./server -c="./config.conf"

Start in background:

nohup ./server -c="./config.conf" >> console.log &

# Installing the Visual Editor (RuleGo-Editor)

RuleGo-Editor is the visual UI interface for RuleGo-Server, used for visual management, debugging, and deployment of rule chains.

# Option 1: Use Pre-built Package (Recommended)

Download editor.zip from Github Releases (opens new window)
Extract it to the same directory as the server binary, which will create an editor folder:

your-app/
├── server          # Server binary
├── config.conf     # Configuration file
└── editor/         # Extracted editor frontend
    ├── index.html
    ├── config/
    │   └── config.js
    └── ...

1
2
3
4
5
6
7
8

Ensure resource_mapping in config.conf is configured correctly (configured by default):

resource_mapping = /editor/*filepath=./editor,/images/*filepath=./editor/images

After starting the server, visit http://localhost:9090/ to open the editor

If the editor is placed in a different path, change ./editor in resource_mapping to the actual path.

# Option 2: Build from Source

Clone the rulego-editor (opens new window) repository
Important: Make sure base in vite.config.js (opens new window) is set to /editor/:

export default defineConfig({
  base: '/editor/',
  // ...
})

1
2
3
4

Install dependencies and build:

npm install
npm run build

1
2

Copy the build output (dist directory contents) to an editor folder in the same directory as the server

# Changing the Backend API Address

If the server is not on localhost or uses a different port, edit baseUrl in editor/config/config.js:

window.baseUrl = 'http://your-server:9090'

# Configuration File Details

The configuration file uses INI format and supports environment variable substitution (${VAR} or ${VAR:-default}). Below is a complete description of all configuration options:

# Basic Configuration

Parameter	Default	Description
`data_dir`	`./data`	Data directory for storing runtime data such as rule chains and components
`server`	`:9090`	HTTP service listen address
`base_path`	(empty)	API route prefix, used in embedded mode
`default_username`	`admin`	Default username when authentication is disabled
`skill_path`	`./skills`	Global Skill storage path (set to `./data/skills` in the built-in config.conf)

# Runtime Configuration

Parameter	Default	Description
`debug`	`true`	Whether to print node debug logs to the log file
`max_node_log_size`	`40`	Maximum number of log entries per node
`script_max_execution_time`	`5000`	Script execution timeout (milliseconds)
`run_log_mode`	`off`	Run log level: `off` (no logging) / `summary` (summary only) / `detail` (full per-node logs). Replaces the former `save_run_log`; per-chain `additionalInfo.runLogMode` can override this global setting
`run_log_store_type`	`bbolt`	Execution log storage backend: `bbolt`, `file` (JSON Lines)
`run_log_retention_count`	`500`	Keep the most recent N log entries per rule chain, 0 means no limit
`run_log_retention_days`	`7`	Keep logs from the most recent N days, 0 means no limit
`share_http_server`	`false`	Inject the main HTTP server into each user's node pool as a shared node; business chains can reuse it via `server: "ref://<server>"`. Use with caution in multi-tenant environments (route conflicts and chain restarts affect all tenants sharing the port)
`endpoint_enabled`	`false`	Whether to enable the endpoint framework (MQTT, Kafka and other external integrations)
`event_bus_chain_id`	(empty)	Rule chain ID for processing core event bus events
`category_folder_enabled`	`false`	Whether to organize rule chains by category folders
`load_lua_libs`	`true`	Whether to load third-party Lua libraries

# HTTP Service Configuration

Parameter	Default	Description
`allow_cors`	`true`	Whether to allow cross-origin requests
`read_timeout`	`30`	HTTP read timeout (seconds)
`write_timeout`	`300`	HTTP write timeout (seconds); AI streaming output requires a larger value
`max_body_size`	`10`	Maximum request body size (MB)

# Log Configuration

Parameter	Default	Description
`log_file`	(empty)	Log file path; if empty, output goes to console
`log_level`	`info`	Log level: `debug`, `info`, `warn`, `error`
`log_max_size`	`100`	Maximum size of a single log file (MB)
`log_max_backups`	`30`	Number of old log files to retain
`log_max_age`	`7`	Log file retention days

# Security Configuration

Parameter	Default	Description
`require_auth`	`false`	Whether to enable JWT authentication
`jwt_secret_key`	(built-in default)	JWT signing secret key; recommended to set via environment variable `JWT_SECRET_KEY`
`jwt_expire_time`	`43200000`	JWT expiration time (milliseconds), default 12 hours
`jwt_issuer`	`rulego.cc`	JWT issuer
`cmd_mode`	`allow`	Shell command security mode: `allow` (whitelist), `deny` (blacklist)
`cmd_white_list`	(built-in list)	List of allowed Shell commands
`cmd_deny_list`	(empty)	List of denied Shell commands
`cmd_deny_args`	(empty)	Denied command argument patterns
`file_path_white_list`	`/tmp`	Path whitelist for file nodes

# AI Tool Security Configuration

The [ai_security] section provides a global pre-check policy for AI tool calls (e.g. restricting tool capabilities in demo environments). Requires the with_ai or with_all build tag, and does not affect the per-agent tool security settings.

Parameter	Default	Description
`enable`	`false`	Whether to enable tool security interception
`mode`	`deny`	Interception mode: `deny` (blacklist, block on match) or `allow` (whitelist, block if not listed)
`deny_tools`	(empty)	Tools to block in deny mode, comma-separated, supports `*` wildcard
`allow_tools`	(empty)	Tools to allow in allow mode, comma-separated, supports `*` wildcard
`denied_types`	(empty)	Tool types to block: `builtin`, `mcp`, `rulechain`, `subagent`
`cmd_deny_extra`	(empty)	Extra command deny list for the bash tool, applied on top of the tool's own security checks
`allow_paths`	(empty)	File path allow list; read/write/edit tools can only access these paths; empty means no restriction
`deny_paths`	(empty)	File path deny list; takes priority over `allow_paths`; supports wildcards (e.g. `./config*`)

# Resource Mapping

# Format: /url/*filepath=/path/to/file, multiple mappings separated by commas
resource_mapping = /editor/*filepath=./editor,/images/*filepath=./editor/images

1
2

# Shared Node Pool

# Node pool file, rule chain JSON format
node_pool_file = ./node_pool.json

1
2

# MCP Configuration

[mcp]
enable = true

1
2

For details, see MCP Service.

# MCP Group Configuration

[mcp.groups]
# Format: group name = tool list (comma-separated)
# Syntax: * = all tools, -prefix* = exclude by prefix,
#         rules/components/chains = tool categories (management API tools/component tools/chain tools)
readonly = rules,list_components,get_component_doc
full = *
no-delete = *,-delete_rule_chain
iot = rules,components,chains,-_assistant

1
2
3
4
5
6
7
8

# Global Custom Configuration

[global]
# Components can access values via ${global.xxx}
sqlDriver = mysql
sqlDsn = root:root@tcp(127.0.0.1:3306)/test
# AI Agent LLM configuration
llm_url = https://api.openai.com/v1
llm_api_key = sk-xxx
llm_model = gpt-4o

1
2
3
4
5
6
7
8

# User Configuration

[users]
# Format: username = password[,apiKey]
# apiKey is optional; when configured, the API can be accessed directly via apiKey without login
admin = admin,ak-your-secret-key
user01 = user01

1
2
3
4
5

# pprof Configuration

[pprof]
enable = false
addr = 0.0.0.0:6060

1
2
3

# Docker Deployment

FROM alpine:latest
COPY server /app/server
COPY config.conf /app/config.conf
COPY editor /app/editor
WORKDIR /app
RUN chmod +x server
EXPOSE 9090
CMD ["./server", "-c=./config.conf"]

1
2
3
4
5
6
7
8

docker build -t rulego-server .
docker run -d -p 9090:9090 -v ./data:/app/data rulego-server

1
2

# Build from Source

# Standard build
go build -o server ./cmd/server/

# With AI components
go build -tags "with_ai" -o server ./cmd/server/

# With all optional components
go build -tags "with_all" -o server ./cmd/server/

# Or specify individually
go build -tags "with_ai,with_iot,with_etl,with_ci,with_extend" -o server ./cmd/server/

1
2
3
4
5
6
7
8
9
10
11

Available build tags:

Tag	Description
`with_all`	All optional components (equivalent to enabling all tags below simultaneously)
`with_ai`	AI-related components (ai/agent nodes, LLM tools, etc.)
`with_iot`	IoT-related components
`with_etl`	ETL data processing components
`with_ci`	CI/CD-related components
`with_extend`	Extended components

# Complete Configuration File Example

# =============================================================================
# Basic Configuration
# =============================================================================
# Data directory
data_dir = ./data
# Global Skill storage path
skill_path = ./data/skills
# HTTP service listen address
server = :9090
# API route prefix (for embedded mode)
#base_path = /rulego
# Default username (used when authentication is disabled)
default_username = admin

# =============================================================================
# Security Configuration
# =============================================================================
# Shell command security mode: allow (whitelist) or deny (blacklist)
cmd_mode = allow
# Shell command whitelist
cmd_white_list = cp,scp,mvn,npm,yarn,git,make,cmake,docker,kubectl,helm,ansible,puppet,pytest,python,python3,pip,go,java,dotnet,gcc,g++,ctest
# Shell command blacklist
cmd_deny_list =
# Denied command argument patterns
cmd_deny_args =
# File node path whitelist
file_path_white_list = /tmp
# Whether to load third-party Lua libraries
load_lua_libs = true

# =============================================================================
# Authentication Configuration
# =============================================================================
# Whether to enable JWT authentication
require_auth = false
# JWT signing secret key (recommended to set via environment variable JWT_SECRET_KEY)
jwt_secret_key = r6G7qZ8xk9P0y1Q2w3E4r5T6y7U8i9O0pL7z8x9CvBnM3k2l1
# JWT expiration time (milliseconds), default 12 hours
jwt_expire_time = 43200000
# JWT issuer
jwt_issuer = rulego.cc
# Global encryption key
#secret_key =

# =============================================================================
# Log Configuration
# =============================================================================
# Whether to record node debugging data
debug = true
# Maximum number of log entries per node
max_node_log_size = 40
# Log file path; if empty, output goes to console
#log_file =
# Log level
#log_level = info
# Maximum size of a single log file (MB)
#log_max_size = 100
# Number of old log files to retain
#log_max_backups = 30
# Log file retention days
#log_max_age = 7

# =============================================================================
# Runtime Configuration
# =============================================================================
# Resource mapping (format: /url/*filepath=/path/to/file, multiple separated by commas)
resource_mapping = /editor/*filepath=./editor,/images/*filepath=./editor/images
# Node pool file
node_pool_file = ./node_pool.json
# Run log level: off (no logging) / summary (summary only) / detail (full per-node logs)
# Per-chain additionalInfo.runLogMode can override this global setting
run_log_mode = off
# Execution log storage backend: bbolt (default) or file (JSON Lines)
#run_log_store_type = bbolt
# Keep the most recent N log entries per rule chain, 0 means no limit
#run_log_retention_count = 500
# Keep logs from the most recent N days, 0 means no limit
#run_log_retention_days = 7
# Script execution timeout (milliseconds)
script_max_execution_time = 5000
# Component marketplace base URL
#marketplace_base_url =
# Inject the main HTTP server into each user's node pool as a shared node (use with caution in multi-tenant environments)
share_http_server = false
# Whether to enable the endpoint framework (MQTT, Kafka and other external integrations)
#endpoint_enabled = true
# Rule chain ID for processing core event bus events
#event_bus_chain_id =
# Whether to organize rule chains by category folders
#category_folder_enabled = false

# =============================================================================
# HTTP Service Configuration
# =============================================================================
# Whether to allow cross-origin requests
allow_cors = true
# HTTP read timeout (seconds)
read_timeout = 30
# HTTP write timeout (seconds); AI streaming output requires a larger value
write_timeout = 300
# Maximum request body size (MB)
max_body_size = 10

# =============================================================================
# AI Tool Security Configuration (requires with_ai / with_all build tag, ignored otherwise)
# =============================================================================
[ai_security]
# Whether to enable tool security interception
enable = false
# Interception mode: deny (blacklist) or allow (whitelist)
mode = deny
# Tools to block in deny mode (comma-separated, supports * wildcard)
#deny_tools = bash,write,edit
# Tools to allow in allow mode
#allow_tools = read,plan,skill
# Tool types to block: builtin, mcp, rulechain, subagent
#denied_types =
# Extra command deny list for the bash tool
#cmd_deny_extra = curl,wget
# File path deny list, takes priority over allow_paths, supports wildcards
#deny_paths = ./config*
# File path allow list, empty means no restriction
#allow_paths = /tmp

# =============================================================================
# MCP Configuration
# =============================================================================
[mcp]
enable = true

# MCP group configuration (supports * wildcard, - exclusion, rules/components/chains category keywords)
[mcp.groups]
manager = preview_rule_chain,save_rule_chain,list_rule_chains,get_rule_chain,delete_rule_chain,operate_rule_chain,execute_rule_chain,list_components,get_component_doc
# readonly = rules,list_components,get_component_doc
# full = *

# =============================================================================
# pprof Configuration
# =============================================================================
[pprof]
enable = false
addr = 0.0.0.0:6060

# =============================================================================
# Global Custom Configuration (components can access values via ${global.xxx})
# =============================================================================
[global]
#sqlDriver = mysql
#sqlDsn = root:root@tcp(127.0.0.1:3306)/test
# AI Agent LLM configuration
#llm_url = https://api.openai.com/v1
#llm_api_key = sk-xxx
#llm_model = gpt-4o

# =============================================================================
# User Configuration (format: username = password[,apiKey])
# =============================================================================
[users]
admin = admin
user01 = user01

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

Edit this page on GitHub

Last Updated: 2026/08/13, 09:22:24

← Overview and Quick Start Authentication and Authorization→