Helyx bot

The Helyx Discord runtime validates its environment, verifies and migrates PostgreSQL, validates explicitly configured module packages, applies their migrations, composes platform services, synchronises guild installations and commands, logs in with the non-privileged Guilds intent, and shuts down Discord, modules, and PostgreSQL safely.

Version-matched public guides, operator runbooks, environment reference material, and module-authoring instructions ship at documentation/README.md inside this npm package. Repository-only docs/ and docs-old/ content is not published.

Command contributions use an explicit registration policy: platform commands remain global, migrated customer commands are projected into enabled guilds, deployment commands stay with their deployment, and internal commands are limited to DISCORD_INTERNAL_GUILD_ID. Global and guild commands are synchronized independently.

Registration uses Discord's bulk-overwrite operation, so both scopes are synchronized to exactly the commands supplied by the active Helyx modules. Duplicate command names and component IDs fail before the bot logs in.

HELYX_GLOBAL_COMMAND_MODE defaults to legacy, preserving customer globals for production and self-hosted deployments during migration. Use platform-only only for an approved clean-slate pilot or final cutover; in that mode startup publishes only platform globals and migrated customer commands come from each guild's command profile and enabled module state.

The built-in global /helyx and /permissions commands are core infrastructure. /helyx gives server owners, administrators and members with Manage Server permission an ephemeral module-management flow. It lists installed feature packages, enables or disables them, stages schema-defined settings, uses native Discord channel and role selectors, validates the complete configuration, and saves through the same versioned configuration and audit services as the dashboard. Dependency rules prevent a required module being disabled or a dependent module being enabled out of order.

/permissions uses an owner/administrator-protected select and modal flow with native Discord selectors to manage inherited module policies and command overrides. Feature packages require an explicit allowlist: hosted distributions carry a reviewed hosted-modules.json catalogue, generated self-host projects use HELYX_MODULE_CATALOGUE_PATH, and HELYX_MODULE_PACKAGES remains an intentional comma-separated override. The sources are merged and de-duplicated. A core distribution has no catalogue and runs core-only when both self-host selectors are empty.

Newly discovered feature modules are disabled for each Discord server by default. In legacy mode their global commands remain registered, but attempts to use a disabled module receive an ephemeral explanation directing the member to /helyx or the dashboard. In platform-only mode, migrated commands are included in a guild only when its command profile selects them. Package upgrades preserve each server's existing enabled or disabled state.

Gateway intents are derived from installed event contributions. The bot always requests Guilds, adds non-privileged reaction access only for reaction modules, and adds the privileged Server Members intent only when an installed module handles member joins. Deployments containing such a module must enable the matching intent in the Discord Developer Portal before startup.

When HELYX_BOT_CONTROL_SECRET is configured, the bot also starts a private authenticated HTTP control server on HELYX_BOT_CONTROL_PORT. The dashboard API uses this service to obtain real Discord roles and channels and to apply validated module, configuration and permission changes. Only /health is unauthenticated; all /v1 routes require the shared bearer secret. Keep this endpoint on a private service network and do not assign it a public domain.

Optional Helyx Cloud Connect is a separate outbound management path for self-hosted deployments. It is disabled unless HELYX_CLOUD_CONNECT_ENABLED=true and requires a separate local HELYX_DATA_ENCRYPTION_KEY. Preserve that key across every restart and deployment. If it is lost or changed, revoke the old installation in the dashboard and use a new one-use code with /helyx-cloud connect; the connector stops retrying until that recovery is completed. The owner-only /helyx-cloud command supports connection-code enrolment, status, credential rotation, disconnection and bounded support consent. The bot never sends its Discord token, database URL or connector private key to Helyx Cloud, and local Discord operation continues when Cloud is unavailable.

Giveaways also requires the existing HELYX_DATA_ENCRYPTION_KEY so core can resume secure weighted-selection checkpoints without exposing the selection key to a module. Keep it stable across deployments; do not rotate it while a giveaway is drawing.

Trivia uses questions already imported into PostgreSQL. Multiple Choice and Guess both run entirely from the saved question catalogue, and the bot runtime does not call an external trivia provider.

The always-available guild-only /bug command can be used by any guild member. Hosted deployments submit through the dedicated HELYX_SUPPORT_SERVICE_SECRET; paired self-hosted deployments use their authenticated Cloud Connect session and may receive a one-time link for claiming, tracking and replying to the report. The hosted secret is never part of a self-host package. Configure HELYX_SUPPORT_STAFF_CHANNEL_ID with DISCORD_INTERNAL_GUILD_ID to deliver bounded new-case metadata to a private staff channel.

Privacy providers ship in the same hosted and self-hosted module packages. HELYX_PRIVACY_ENABLED defaults to false; enabling it requires the private bot-control endpoint and a separate least-privilege PostgreSQL executor credential. The bot refuses Privacy execution when that credential resolves to the ordinary runtime database role.

Shard configuration and operations

HELYX_SHARD_MODE=off is the default and compatibility baseline. It runs the existing unsharded bot path. Do not set shard-only tuning values in this mode: startup rejects shard count, workers, Redis, generation, database budget and explicit database-pool settings. The internal /dev diagnostics remain available in this mode when their guild and role configuration is present.

| Mode | Required values | Prohibited values | Behaviour | | ------- | ---------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------- | | off | None | Shard count, workers, Redis, namespace, generation, budget and explicit pools | Existing single-process behaviour | | auto | None for local mode | Shard count; Redis and namespace unless coordinated | Obtains Discord's recommended total | | fixed | HELYX_SHARD_COUNT (1-4096) | None beyond the scope rules | Uses the deliberate total; workers per replica may not exceed it |

HELYX_SHARD_SCOPE defaults to local; use it for one supervisor host. coordinated is only valid in a sharded mode and requires all of HELYX_SHARD_REDIS_URL (redis: or rediss:), HELYX_SHARD_REDIS_NAMESPACE (lowercase safe 3-128-character namespace), and HELYX_SHARD_GENERATION (safe 1-128-character identifier). Redis URL and namespace are forbidden in local mode. Generation is optional for local sharded mode and forbidden when sharding is off.

HELYX_SHARD_WORKERS_PER_REPLICA is a positive integer up to 64 and defaults to 1 when off or 2 when sharded. In sharded modes HELYX_SHARD_SUPERVISOR_DATABASE_POOL_MAX and HELYX_SHARD_WORKER_DATABASE_POOL_MAX default to 2 and 4 respectively (each may be 1-20). HELYX_SHARD_DATABASE_CONNECTION_BUDGET is required for any production sharded mode, optional elsewhere, and may not exceed 1000. When it is set, the following must fit:

supervisor pool + (workers per replica x worker pool) + (2 when Privacy is enabled) <= database budget

Record the provider's actual connection, memory, CPU and replica limits before choosing workers or pools; this repository does not declare a measured production budget.

DISCORD_INTERNAL_GUILD_ID registers the private /dev command only in the exact internal guild. APPROVED_ROLES is a de-duplicated, comma-separated list of at most 100 Discord role IDs. A caller must have Discord's Administrator permission or at least one approved role; role names are never used for authorization. Every response is ephemeral and read-only:

• /dev shards reports bounded shard health, including the unsharded compatibility baseline;
• /dev bot reports the bot build and bounded installed-module versions;
• /dev proc reports safe metrics for the process handling the command.

No /dev command exposes tokens, URLs, Redis keys, database details, environment variables or process arguments. Future developer subcommands must extend this guild-only /dev root and reuse the same authorization boundary. Hosted operators with operations.read can use the Admin Operations shard view instead.

For self-hosting, leave the default off unless the owner has sized the local machine and database. auto with the default local scope is the supported advanced local path and does not require Redis. Coordinated multi-host self-hosting is outside the first release.

Changing the total shard count redistributes guild ownership. Treat it as a generation change: drain the old generation before admitting the new one and never run both as active owners. Shard-capable code does not authorize hosted activation. Phase 10 production activation, replica scaling, or any Railway variable change requires separate owner authorization; do not provision a new Redis or coordinator service for sharding.

For packaged operation use helyx start. helyx migrate applies core database migrations without Discord, and read-only helyx doctor verifies environment, PostgreSQL migration history, and configured package metadata.