Native OS Services
Relevant source files
The following files were used as context for generating this wiki page:
Native OS Services in OneBots provide background execution and lifecycle management for the bot gateway and the management console across Linux, macOS, and Windows. The system abstracts platform-specific daemon managers—such as systemd, launchd, and the Windows Task Scheduler—into a unified CLI and programmatic interface.
This service layer ensures that the management console remains available even if the bot gateway stops or fails. It supports both user-level and system-level scopes for service installation and execution.
Sources: README.en.md:88-92, AGENTS.md:12-16
Service Architecture
OneBots distinguishes between the management service (Control) and the gateway runtime (Gateway). The management service acts as a persistent host that manages installation plans, runtime versions, and configurations.
Service Types
| Service Role | Component | Functionality |
|---|---|---|
| Control (Manager) | onebots serve | Persistent management console, handles authentication, updates, and plugin installation. |
| Gateway (Runner) | onebots start | Active bot process that executes adapters and protocols based on the current active runtime version. |
Sources: AGENTS.md:65-70, packages/onebots/src/manager-service-definition.spec.ts:13-23
Service Relationship Flow
The diagram below illustrates how the CLI interacts with the OS Service Manager to host OneBots components.
This diagram shows the relationship between the CLI commands, the underlying OS service management system (systemd/launchd), and the two primary service roles.
Sources: README.en.md:92-96, AGENTS.md:16-20
Service Specifications
The project uses structured specification objects to define service behavior, paths, and environment variables. These specs are used by platform-specific renderers to generate service definition files.
Manager Service Specification
The ManagerServiceSpec defines the configuration for the persistent control service.
| Field | Description |
|---|---|
runtimeKind | Must be set to control. |
scope | Service visibility: user or system. |
workspace | The data directory where configurations and logs are stored. |
nodePath | Path to the Node.js executable used to run the service. |
binPath | Path to the OneBots entry point script (bin.js). |
host / port | Network binding for the management API (default port 6727). |
Sources: packages/onebots/src/manager-service-definition.spec.ts:13-23, AGENTS.md:73-77
Gateway Service Specification
The ServiceSpec (Legacy/Runner) defines how the bot gateway runs, including the specific adapters and protocols to enable at startup.
| Field | Description |
|---|---|
configPath | Path to the config.yaml file. |
adapters | List of platform adapters to load (e.g., qq, kook). |
protocols | List of wire protocols to export (e.g., onebot-v11). |
workingDirectory | The execution context for the gateway process. |
Sources: packages/onebots/src/service-definition.spec.ts:16-24, packages/onebots/src/legacy-service-inspection.spec.ts:31-39
Platform Implementation
OneBots provides specific renderers for different operating systems to ensure native integration.
Linux (systemd)
Systemd units are generated as .service files. The renderer protects arguments with quotes and escapes systemd specifiers (e.g., % becomes %%).
- Unit Files: Uses
ExecStartfor execution andWorkingDirectoryfor process context. - Reliability: Implements
KillMode=mixed,Restart=on-failure, and a definedTimeoutStopSec. - Targets:
userscope services useWantedBy=default.target, whilesystemscope services useWantedBy=multi-user.target.
Sources: packages/onebots/src/manager-service-definition.spec.ts:28-48, packages/onebots/src/service-definition.spec.ts:40-45
macOS (launchd)
Launchd integration uses .plist files stored in the user's LaunchAgents or the system LaunchDaemons directory.
- Labels: Services are identified by the
onebots.gatewayoronebots.managerlabel. - IO Redirection: Configures
StandardOutPathandStandardErrorPathfor logging. - KeepAlive: Configured with
SuccessfulExit: falseto ensure the service restarts on unexpected crashes.
Sources: packages/onebots/src/manager-service-definition.spec.ts:49-55, packages/onebots/src/service-definition.spec.ts:47-49
Windows
Windows services are supported through the onebots-windows-host executable or XML task definitions for the Task Scheduler.
- Command Rendering: Generates shell commands with
--service-runtime runflags. - Task XML: Includes
<RestartOnFailure>settings for service persistence.
Sources: packages/onebots/src/service-definition.spec.ts:50-59
Lifecycle and Inspection
Service Inspection
The LegacyServiceInspection class validates existing service definitions against the current expected specification. It detects "drift" if the definition file (e.g., systemd unit) does not match the metadata or if the file permissions are too broad (e.g., writable by others).
Sources: packages/onebots/src/legacy-service-inspection.spec.ts:56-78
Lifecycle Sequence
This diagram outlines the process of validating a service's state and configuration before performing lifecycle actions.
Sources: packages/onebots/src/legacy-service-inspection.spec.ts:48-55, README.en.md:98-102
Summary of Commands
| Command | Action | Scope |
|---|---|---|
onebots install | Registers the service with the OS. | User (default) |
onebots start | Signals the OS to run the service. | User/System |
onebots status | Queries the current execution state. | User/System |
onebots logs | Retrieves background process output. | User/System |
onebots doctor | Diagnoses installation and service health. | N/A |
Sources: README.en.md:88-92, AGENTS.md:120-125
Native OS Services ensure OneBots operates as a reliable background infrastructure, providing standardized management of bot runtimes across diverse operating environments.