Kirin

Clusterable/container-ready MX server built on smtp-server.

Kirin is a small SMTP receiver built on smtp-server. It exposes ZoneMTA-compatible receiver hooks through @zone-eu/wild-plugins and can run directly with Node.js or in a container.

Features

• Single-process runtime designed for container orchestration
• ZoneMTA-compatible SMTP hook contracts
• Configurable SMTP size, connection, authentication, proxy, and TLS settings
• Graceful signal handling and plugin shutdown hooks
• Docker image support
• Strict TypeScript source and contract tests
• Dual ESM and CommonJS package exports

Requirements

• Node.js 20 or newer
• npm
• Docker (optional)

Quick start

Install the locked dependency set and run the checks:

npm ci
npm run check

Start the receiver:

npm start

The development default listens on 127.0.0.1:2525. It does not advertise AUTH or STARTTLS and does not load a delivery plugin.

Configuration

Configuration is loaded by @zone-eu/wild-config. The repository defaults are in config/default.toml. Keep deployment settings and secrets outside the repository and load them with NODE_CONFIG_PATH or --config:

NODE_CONFIG_PATH=/etc/kirin.toml npm start
npm start -- --config=/etc/kirin.toml

Existing values can also be overridden with APPCONF_ environment variables or dotted command-line arguments:

APPCONF_smtp_port=2500 npm start
npm start -- --smtp.port=2500

Inspect the fully merged configuration without starting the SMTP listener:

npm run show-config

Important settings include:

• smtp.host, smtp.port, and smtp.name: listener and SMTP identity
• smtp.size: advertised and enforced maximum message size in bytes
• smtp.dataHookTimeout: maximum duration of the DATA plugin hook in milliseconds
• smtp.maxClients: maximum simultaneous SMTP connections
• smtp.authentication: whether AUTH may be advertised
• smtp.authOptional: whether unauthenticated mail commands are permitted
• smtp.disableSTARTTLS: whether the STARTTLS command is disabled
• smtp.tls: paths to the private key, certificate, and optional CA bundle
• plugins.pluginsPath: base directory used to resolve plugin directories
• plugins.conf: optional plugin configuration included from config/plugins/*.toml

TLS and authentication

STARTTLS is disabled in the development configuration because no certificate or private key is bundled. To enable it, use deployment-specific configuration that sets smtp.disableSTARTTLS = false and supplies readable smtp.tls.keyPath and smtp.tls.certPath files.

Setting smtp.authentication = true is not sufficient by itself: an enabled plugin must implement smtp:auth. Set smtp.authOptional = false only after that hook is configured and tested. Do not offer plaintext authentication over an unencrypted public connection.

Plugins

Plugin settings are included by this directive in config/default.toml:

[plugins]
pluginsPath = "."

[plugins.conf]
# @include "plugins/*.toml"

The plugin path is resolved from the repository root. For example, the config key example-plugin resolves to the directory ./example-plugin. No plugin code or plugin configuration is included by default. Add plugin configuration under config/plugins/, keep its secrets in deployment-specific configuration, and set the plugin's enabled value explicitly. Plugins run in ascending ordering value.

The receiver exposes these hooks:

• smtp:connect(session)
• smtp:auth(auth, session)
• smtp:mail_from(address, session)
• smtp:rcpt_to(address, session)
• smtp:data(envelope, session)

The receiver-specific connection and transaction adapters remain internal. A plugin can obtain the matching connection through the plugin handler's getConnection(session) helper.

Message buffering

SMTP DATA is fully buffered in memory before smtp:data(envelope, session) runs. The buffer is released immediately after the hook completes, fails, or times out. The smtp-server size option advertises and enforces smtp.size, oversized messages receive a 552 response after the input stream has been drained.

Memory use therefore scales with message size and concurrent DATA sessions. Choose conservative smtp.size and smtp.maxClients values for the available memory before exposing the service to untrusted clients.

Unhandled promise rejections and uncaught exceptions are logged without explicitly terminating the process. Startup is attempted once and a failed startup is not retried. Kirin does not fork or supervise child processes, run one process per container and scale with Kubernetes replicas or another external supervisor.

Container

Build and run the image:

docker build -t kirin .
docker run --rm -p 2525:2525 kirin

The image sets the in-container listener to 0.0.0.0, publishing the port is still an explicit docker run choice.

Pass APPCONF_ environment variables with -e to override configuration. Replace dots in configuration paths with underscores and preserve the key's capitalization: smtp.maxClients becomes APPCONF_smtp_maxClients. For example, set the SMTP hostname, listener port, connection limit, and log level:

docker run --rm -p 2525:2500 \
  -e APPCONF_smtp_name=mx.example.com \
  -e APPCONF_smtp_port=2500 \
  -e APPCONF_smtp_maxClients=100 \
  -e APPCONF_log_level=debug \
  kirin

The right-hand port in -p must match smtp.port inside the container. In this example, host port 2525 forwards to container port 2500.

For multiple settings, create a deployment-specific kirin.env file:

APPCONF_smtp_name=mx.example.com
APPCONF_smtp_port=2525
APPCONF_smtp_size=10485760
APPCONF_smtp_maxClients=100
APPCONF_smtp_disableSTARTTLS=true
APPCONF_log_level=info

Load it with Docker's --env-file option:

docker run --rm --env-file ./kirin.env -p 2525:2525 kirin

Environment overrides only apply to keys already defined in the loaded configuration. Their existing types determine how numbers, booleans, and strings are parsed. Use true or false for boolean settings. Environment variables override configuration files, and command-line arguments override environment variables. Keep deployment files containing secrets outside the repository.

To inspect the merged configuration without starting the listener:

docker run --rm --env-file ./kirin.env -e NODE_CONFIG_ONLY=true kirin

The output includes configuration values, so avoid sharing it if it contains secrets. To use an external configuration file, optionally combined with the environment overrides above:

docker run --rm -p 2525:2525 \
  -v /etc/kirin.toml:/run/kirin.toml:ro \
  kirin --config=/run/kirin.toml

TypeScript package

Kirin's source is plain TypeScript under src/. A build produces ESM, CommonJS, and format-specific declaration outputs under dist/. Install the scoped package and use the async factory for normal embedding:

npm install @zone-eu/kirin

import { createKirinServer } from '@zone-eu/kirin';

const server = await createKirinServer({ config });
await server.start();

const { createKirinServer } = require('@zone-eu/kirin');

async function main() {
    const server = await createKirinServer({ config });
    await server.start();
}

main().catch(console.error);

createKirinServer() creates the default logger and loads configured plugins. Advanced callers can still construct KirinServer with an initialized logger and plugin handler. An installed package also provides a kirin executable, so another project's npm script can invoke it directly or with npx kirin.

The package root intentionally does not set a global module type. Generated ESM and CommonJS directories define their own module boundaries, so existing CommonJS receiver plugins using .js files continue to load normally.

Development commands

npm run build          # build ESM, CommonJS, and declaration output
npm test               # build and run the typed Mocha suite
npm run typecheck      # type-check source, tests, and build tooling
npm run lint           # run type-aware ESLint rules
npm run format:check   # verify Prettier formatting
npm run check          # run all static checks, build, and tests
npm run show-config    # print merged configuration and exit

Before a production deployment, configure durable delivery, use a real SMTP hostname and DNS records, supply TLS certificates, rotate all plugin secrets, restrict trusted proxy extensions, set resource limits, and add service supervision and monitoring.

Kirin Mail Server is part of the Zone Mail Suite (ZMS). Suite of programs and modules for an efficient, fast and modern email server.

Copyright (c) 2026 Zone Media OÜ.