Skip to main content
Version: 3.63.0

Configuration

Platformatic Runtime is configured with a configuration file. It supports the use of environment variables as setting values with environment variable placeholders.

Configuration Files​

The Platformatic CLI automatically detects and loads configuration files found in the current working directory with the file names listed here.

Alternatively, you can use the --config option to specify a configuration file path for most wattpm CLI commands. The configuration examples in this reference use the JSON format.

Supported File Formats​

For detailed information on supported file formats and extensions, please visit our Supported File Formats and Extensions page.

Settings​

Configuration settings containing sensitive data should be set using environment variable placeholders.

info

The autoload and applications settings can be used together, but at least one of them must be provided. When the configuration file is parsed, autoload configuration is translated into applications configuration.

autoload​

The autoload configuration is intended to be used with monorepo applications. autoload is an object with the following settings:

  • path (required, string) - The path to a directory containing the applications to load. In a traditional monorepo application, this directory is typically named packages.
  • exclude (array of strings) - Child directories inside path that should not be processed.
  • mappings (object) - Each applicaiton is given an ID and is expected to have a Platformatic configuration file. By default, the ID is the application's directory name, and the configuration file is expected to be a well-known Platformatic configuration file. mappings can be used to override these default values. Supported properties are the same of entries in application, except path, url, and gitBranch.

preload​

The preload configuration is intended to be used to register Application Performance Monitoring (APM) agents. preload should contain a path or a list of paths pointing to a CommonJS or ES module that is loaded at the start of the app worker thread.

extensions​

While preload injects code in each application worker thread, extensions loads custom code in the runtime main thread. Extensions can observe and control the whole runtime: they receive the Runtime object and an ITC (Inter-Thread Communication) facade which allows them to register custom commands that applications can invoke from their worker threads.

extensions can be a path, an object with path and options properties, or an array of either:

{
  "extensions": [
    {
      "path": "./runtime-extension.js",
      "options": {
        "bucket": "{S3_BUCKET}"
      }
    }
  ]
}

Each file must default-export a setup function, which is invoked during the runtime initialization, before any application is started. TypeScript files are supported out of the box via Node.js type stripping.

export default async function setup ({ runtime, itc, sharedContext, logger, options, root, metrics, health }) {
  // React to runtime events
  runtime.on('application:worker:started', payload => {
    logger.info({ payload }, 'worker started')
  })

  // Publish state to every application worker
  await sharedContext.update({ reconciler: { ready: true } })

  // Register a custom command that applications can invoke via
  // getITC().send('acme:hello', payload)
  itc.handle('acme:hello', async payload => {
    return { hello: payload.name }
  })

  // Register main-thread metrics with the shared Runtime metrics pipeline
  const { client, registry } = metrics
  const jobs = new client.Gauge({
    name: 'acme_extension_jobs',
    help: 'Number of jobs tracked by the extension',
    registers: [registry]
  })
  jobs.set(0)

  // Contribute readiness/liveness checks and diagnostic routes on the health probes server
  health.registerReadinessCheck('dispatchable', async () => {
    return { status: true }
  })

  health.registerLivenessCheck('control-plane', async () => true)

  health.registerRoutes(async app => {
    app.get('/inventory', async () => ({ ok: true }))
  })

  return {
    async start () {
      // Invoked after applications are prepared, before they accept traffic.
      // Can add/start dynamic applications; Runtime will not start them again.
    },
    async stop () {
      // Invoked during shutdown after the entrypoint stops and before remaining
      // applications stop. Useful for control-plane handoff.
    },
    async close () {
      // Invoked when the runtime is closed, after all applications have stopped.
    }
  }
}

The setup function receives a context object with the following properties:

  • runtime - The Runtime instance. It is an EventEmitter, so extensions can subscribe to all runtime events and invoke any public method, including application and worker introspection (getApplications(), getWorkers()), application configuration and environment (getApplicationConfig(id), getApplicationEnv(id)), and metrics (getMetrics()).

  • itc - A facade over the runtime ITC:

    • handle(name, handler) - Registers a custom command invocable from any application via the ITC API returned by getITC() from @platformatic/globals. The name must not clash with the commands reserved by the runtime or with a command registered by another extension.
    • send(target, name, payload) - Sends a request to a worker and awaits its response. target is an application ID (a worker is chosen in round-robin) or application:worker-index for a specific worker.
    • notify(target, name, payload) - Sends a fire-and-forget notification. When target is an application ID, all its running workers are notified; use application:worker-index to target a specific worker. Workers receive notifications via getITC().on(name, handler).

  • sharedContext - The shared context API used by application workers. get() synchronously returns a snapshot of the current context in main-thread extensions. update(update, options?) merges update into the context and broadcasts the result to every running worker; pass { overwrite: true } to replace the context instead. Newly started workers receive the latest context. Use update() rather than mutating the object returned by get().

  • logger - A child of the runtime logger.

  • options - The options object specified in the configuration, if any.

  • root - The runtime project root directory.

  • metrics - A per-extension Prometheus client and registry:

    • client - The @platformatic/prom-client module (same client used by application workers).
    • registry - A dedicated Registry for this extension. Metrics registered here appear once in Runtime.getMetrics(), the management metrics API, and the existing /metrics endpoint. They are not duplicated per application worker.

    Label behavior: extension metrics are main-thread metrics. Runtime never invents a workerId or application ID label for them. Only static labels from the runtime metrics.labels configuration are applied (the configured application label name is omitted, same as process-level metrics). Extensions that need application- or worker-specific labels must set them explicitly when creating metrics.

    Metric family names must be unique across extensions and must not collide with runtime process metrics, restart metrics, or application worker metrics. Collisions fail with PLT_RUNTIME_METRIC_FAMILY_COLLISION, identifying the extension and metric family. The registry is cleared when the extension closes (including partial startup failures).

  • health - API for contributing readiness/liveness checks and diagnostic routes on Watt's health probes server (the metrics server when probes are shared with it, or the dedicated health probes server when configured separately):

    • registerReadinessCheck(name, check) - Registers a named check that participates in /ready. Check names must be unique across extensions. The check may return a boolean or { status, statusCode?, body? }. Rejected, timed-out, or malformed checks fail closed. Timeouts use the configured health checks timeout. Readiness-only failures do not fail /status (liveness), so a temporary control-plane condition can stop traffic without triggering a pod restart loop. Returns an unregister function.
    • registerLivenessCheck(name, check) - Same contract as readiness, but the check participates in /status. Returns an unregister function.
    • registerRoutes(plugin) - Registers a Fastify plugin on the health probes server before it starts listening. Works for shared and separate probe servers. Route collisions fail startup with a coded error identifying the extension and route. Returns an unregister function that disables the routes. Closing the extension removes its checks and routes.

The setup function can optionally return an object with awaited lifecycle hooks:

  • start() - Called once applications have been prepared and registered, and before the originally configured applications start accepting traffic. Runtime awaits every extension start hook. An extension may add and start dynamic applications here; those applications are excluded from the normal startup pass so they are not started twice. Runtime does not report started until extension and application startup complete. If a later extension or application fails, Runtime stops and closes already-started extensions during cleanup.
  • stop() - Called during shutdown after the entrypoint has been stopped and before the remaining applications stop. Runtime awaits every extension stop hook so control-plane extensions can settle work and hand off state.
  • close() - Called when the runtime is being closed, after applications have stopped. The extension metrics registry is cleared after close.

When multiple extensions are configured, they are set up and started in registration order. stop and close run in reverse registration order. Each of stop and close is invoked at most once per Runtime life, including repeated stop/close calls and failed-start cleanup paths. Existing extensions that only return close() keep their previous behavior. Health checks and routes registered by an extension are cleaned up with it.

Listening to Runtime EventEmitter events is not a substitute for these hooks: emit() does not await asynchronous listeners. Lifecycle ordering is enforced by Runtime itself so it covers signal handling, internal failure cleanup, and future lifecycle entry points.

Extensions are not loaded when building the applications (for example via wattpm build).

For a complete worked example — enabling continuous profiling on every worker when it starts (or is restarted) and shipping the captured profiles — see the Capture Flamegraphs on Health Events guide.

applications​

applications is an array of objects that defines the applications managed by the runtime. Each application object supports the following settings:

  • id (required, string) - A unique identifier for the application.

  • enabled (boolean, string, or object) - If false, the application is disabled and will not be loaded by the runtime. Boolean strings and environment variable placeholders are supported. It can also be an object where each key is an environment name and each value is a boolean. If the current environment does not match any key, the application is enabled. Default: true.

  • path (required, string) - The path to the directory containing the application. It can be omitted if url is provided.

  • url (required, string) - The URL of the application remote GIT repository, if it is a remote application. It can be omitted if path is provided. You can specify a branch using the URL fragment syntax: https://github.com/user/repo.git#branch-name.

  • gitBranch (string) - The branch of the application to resolve. Takes precedence over the branch specified in the URL fragment.

  • config (string) - The configuration file used to start the application.

  • useHttp (boolean) - The application will be started on a random HTTP port on 127.0.0.1, and exposed to the other applications via that port, on default it is set to false. Set it to true if you are using @fastify/express.

  • reuseTcpPorts: Enable the use of the reusePort option whenever any TCP server starts listening on a port. The default is true. The values specified here overrides the values specified in the runtime.

  • workers - The number of workers to start for this application. If the application is the entrypoint or if the runtime is running in development mode this value is ignored and hardcoded to 1. This can be specified as:

    • number - A fixed number of workers
    • object - Advanced worker configuration with the following properties:
      • static (number) - A fixed number of workers
      • dynamic (boolean) - Enable dynamic worker scaling. This is only meaningful when set to false to disable dynamic scaling for this application.
      • minimum (number) - Minimum number of workers when using dynamic scaling
      • maximum (number) - Maximum number of workers when using dynamic scaling

  • health (object): Configures the health check and low-level resource defaults for each worker of the application. It supports all the properties also supported in the runtime health property. The values specified here override the values specified in the runtime.

  • arguments (array of strings) - The arguments to pass to the application. They will be available in process.argv.

  • envfile (string) - The path to an .env file to load for the application. By default, the .env file is loaded from the application directory.

  • env (object) - An object containing environment variables to set for the application. Values set here takes precedence over values set in the envfile.

  • sourceMaps (boolean) - If true, source maps are enabled for the application. Default: false.

  • packageManager (string) - The package manager to use when using the install-dependencies or the resolve commands of wattpm-utils. Default is to autodetect it, unless it is specified via command line.

  • preload (string or array of strings): A file or a list of files to load before the application code.

  • nodeOptions (string): The NODE_OPTIONS to apply to the application. These options are appended to any existing option.

  • execArgv (array of strings): Additional arguments to pass to application worker threads via the execArgv option. These arguments are passed to the Node.js executable when creating worker threads. See Node.js Worker Threads documentation for more information. Note that execArgv options are automatically inherited by any child worker threads created by the application.

  • permissions (object): Configure application-level security permissions to restrict file system access. Supported properties are:

    • fs:
      • read (array of strings): Array of file system paths the application is permitted to read from. Uses the same syntax as Node.js --allow-fs-read.
      • write (array of strings): Array of file system paths the application is permitted to write to. Uses the same syntax as Node.js --allow-fs-write.

    When filesystem permissions are enabled, certain paths are automatically added to maintain application functionality:

    • The current Watt project's node_modules directory
    • The application's own node_modules directory
    • Any node_modules directories found in parent directories of the runtime path

    The security permissions are based on Node.js permission model and therefore the application will have restricted access to native modules, child processes, worker threads, the inspector protocol, and WASI. See the Node.js Permission Model Constraints for complete details.

  • dependencies (array of strings): A list of applications that must be started before attempting to start the current application. Note that the runtime will not perform any attempt to detect or solve dependencies cycles.

  • management (boolean or object): Grants the application access to runtime management operations via the ITC (Inter-Thread Communication) channel. See the management section for details.

  • telemetry (object): containing an instrumentations array to optionally configure additional open telemetry intrumentations per application, e.g.:

"applications": [
    {
      "id": "api",
      "path": "./services/api",
      "telemetry": {
        "instrumentations": ["@opentelemetry/instrumentation-express"]
      }
    }
  ]

It's possible to specify the name of the export of the instrumentation and/or the options:

"applications": [
    {
      "id": "api",
      "path": "./services/api",
      "telemetry": {
        "instrumentations": [{
          "package": "@opentelemetry/instrumentation-express",
          "exportName": "ExpressInstrumentation",
          "options": {}
        }]
      }
    }
  ]

An alias for applications. If both are present, their content will be merged.

It's also possible to disable the instrumentation by setting the enabled value property to false (env variables are also supported):

"applications": [
    {
      "id": "api",
      "path": "./services/api",
      "telemetry": {
        "enabled": "false",
        "instrumentations": [{
          "package": "@opentelemetry/instrumentation-express",
        }]
      }
    }
  ]

env​

An object containing environment variables to set for all applications in the runtime. Any environment variables set in the env object will be merged with the environment variables set in the envfile and env properties of each application, with application-level environment variables taking precedence.

envfile​

The path to an .env file to load for the runtime. By default, the .env file is loaded from the application directory.

strictEnv​

Controls what happens when a {PLT_*} environment variable placeholder references a variable which is not set:

  • false (the default): the placeholder is silently replaced with an empty string.
  • true: loading the configuration fails at startup with an error listing all the missing variables.
  • "warn": a warning listing the missing variables is logged, but the placeholders are still replaced with an empty string.

The value is also applied when loading the configuration files of the applications in the runtime.

{
  "strictEnv": true
}

sourceMaps​

If true, source maps are enabled for all applications. Default: false. This setting can be overridden at the application level.

resolvedServicesBasePath​

The base path, relative to the configuration file to store resolved applications. Each application will be saved in {resolvedServicesBasePath}/{id}. Default: external.

entrypoint​

The Platformatic Runtime's entrypoint is an application that is exposed publicly. This optional value must be the ID of an application defined via the autoload or applications configuration.

If entrypoint is omitted, the runtime automatically selects one when there is a single application or exactly one Gateway application. If it cannot select a single entrypoint, the runtime starts without a public entrypoint; applications remain reachable through their internal .plt.local URLs and APIs such as runtime.inject().

workers​

Configures the default number of workers to start per each application. Some values can be overridden at the application level.

This can be specified as:

  • number - A fixed number of workers (minimum 1)
  • object - Advanced worker configuration with the following properties:
    • static (number) - A fixed number of workers
    • dynamic (boolean) - Enable dynamic worker scaling (default: false). The dynamic worker scaler automatically adjusts the number of workers for each application based on Event Loop Utilization (ELU) and available system memory. It can be overridden at the application level.
    • minimum (number) - The minimum number of workers that can be used for each application. Default: 1.
    • maximum (number) - The maximum number of workers that can be used for each application. Default: global total value.
    • total (number) - The maximum number of workers that can be used for all applications. Default: os.availableParallelism() (typically the number of CPU cores).
    • maxMemory (number) - The maximum total memory in bytes that can be used by all workers. Default: 90% of the system's total memory.
    • cooldown (number) - The amount of milliseconds the scaling algorithm will wait after making a change before scaling up or down again. This prevents rapid oscillations. Default: 20000.
    • gracePeriod (number) - The amount of milliseconds after a worker is started before the scaling algorithm will start collecting metrics for it. This allows workers to stabilize after startup. Default: 30000.

This value is hardcoded to 1 if the runtime is running in development mode or when applying it to the entrypoint.

workersRestartDelay​

Configures the amount of milliseconds to wait before replacing another worker of an application during a restart.

gracefulShutdown​

Configures the amount of milliseconds to wait before forcefully killing an application or the runtime.

The object supports the following settings:

  • application (number) - The graceful shutdown timeout for an application. Default: 10000 (ten seconds).
  • runtime (number) - The graceful shutdown timeout for the entire runtime. Default: 30000 (thirty seconds).

watch​

An optional boolean, set to default false, indicating if hot reloading should be enabled for the runtime. If this value is set to false, it will disable hot reloading for any applications managed by the runtime. If this value is true, then hot reloading for individual applications is managed by the configuration of that application.

Note that watch should be enabled for each individual application in the runtime.

warning

While hot reloading is useful for development, it is not recommended for use in production.

startTimeout​

The number of milliseconds to wait before considering an application as failed to start. Default: 30000.

restartOnError​

The number of milliseconds to wait before attempting to restart an application that unexpectedly exit.

If not specified or set to true, the default value is 5000, set to 0 or false to disable.

Any value smaller than 10 will cause immediate restart of the application.

This setting is ignored in production, where applications are always restarted immediately.

exitOnUnhandledErrors​

When enabled (default), Platformatic automatically installs error handlers for uncaughtException and unhandledRejection events on each worker process. These handlers will automatically restart the affected worker when such errors occur.

If application code installs its own listeners for these events, Platformatic tracks them, removes them from process, and invokes them before terminating the worker. This keeps Platformatic in control of the shutdown while still allowing error reporting tools to observe fatal errors.

Set this to true to terminate the worker after 100 milliseconds. Set this to a positive number to use that number of milliseconds instead.

Setting this to false, 0, or a negative number disables the automatic error handling, making you responsible for implementing proper error handling in your application code.

health​

Configures per-worker health checks and low-level worker resource defaults. Health checks are enabled only if restartOnError is greater than zero; bufferPoolSize and defaultHighWaterMark are applied during worker startup regardless.

The object supports the following settings:

  • enabled (boolean): If to enable the health check. Default: true.
  • interval (number): The interval between checks in milliseconds. Default: 30000.
  • gracePeriod (number): How long after the application started before starting to perform health checks. Default: 30000.
  • maxUnhealthyChecks (number): The number of consecutive failed checks before killing the worker. Default: 10.
  • maxELU (number): The maximum allowed Event Loop Utilization. The value must be a percentage between 0 and 1. Default: 0.99.
  • maxEventLoopDelay (number): The maximum allowed event loop delay in milliseconds. When set, each worker samples its own event loop delay (via perf_hooks.monitorEventLoopDelay) and reports it once per second as an eventLoopDelay health signal; a worker whose maximum delay over a check window exceeds this value counts as unhealthy. This catches long individual stalls at low average utilization (a 150ms synchronous stall each second is an ELU of just 0.15), which are invisible to maxELU. Disabled by default.
  • maxEventLoopDelayP99 (number): The maximum allowed p99 event loop delay in milliseconds. Same mechanism as maxEventLoopDelay, but evaluated against the worst per-second p99 reported over the check window instead of the absolute maximum, so single outlier stalls are smoothed out. Either option activates the sampler; they can be combined. Disabled by default.
  • maxHeapUsed (number): The maximum allowed memory utilization. The value must be a percentage between 0 and 1. Default: 0.99.
  • maxHeapTotal (number or string): The maximum allowed memory allocatable by the process. The value must be an amount in bytes, in bytes or in memory units. Default: 4GB.
  • maxYoungGeneration(number or string): The maximum amount of memory that can be used by the young generation. The value must be an amount in bytes, in bytes or in memory units. Default: 128MB
  • codeRangeSize (number or string): The maximum amount of memory that can be used for code range (compiled code). The value must be an amount in bytes or in memory units. Default: 268435456 (256MB).
  • bufferPoolSize (number or string): Sets Node.js Buffer.poolSize for each application worker. The value must be an amount in bytes or in memory units. Default: 262144 (256KB).
  • defaultHighWaterMark (number or string): Sets the default high water mark for byte streams via Node.js stream.setDefaultHighWaterMark(false, value). The value must be an amount in bytes or in memory units. Default: 262144 (256KB).

bufferPoolSize is intentionally larger than the Node.js default and should be treated as an aggressive server-oriented default. Node.js pools Buffer.allocUnsafe() allocations only when size < (Buffer.poolSize >>> 1), so the 256KB default serves allocations smaller than 128KB from the pool. This covers common server allocation sizes such as HTTP parser buffers, stream chunks, and small file reads in the 4KB-64KB range, reducing allocator work and Worker-thread contention. The trade-off is one larger pool per worker/realm, and RSS can stay higher while pooled slices are retained; lower this value for memory-constrained deployments.

healthProbes​

Enables the Kubernetes readiness and liveness probe endpoints. It can be a boolean, a string, or an object. Default: true.

If healthProbes is true, unset, or a string, the probe endpoints are installed on the Prometheus server. Individual probe endpoints can still be configured with metrics.readiness and metrics.liveness.

Set this to false to disable both probe endpoints globally.

Use an object to configure the health probes server. Health probes are exposed on a standalone server only when the resolved hostname and port differ from the Prometheus server. Otherwise, they are installed on the Prometheus server.

  • enabled (boolean or string). Enables the health probe endpoints. Default: true.
  • hostname (string). The hostname where the health probes server will be listening. Default: 0.0.0.0.
  • port (number or string). The port where the health probes server will be listening. Default: 9090.
  • readiness (object or boolean). Optional readiness endpoint configuration. If omitted, metrics.readiness is used when present.
  • liveness (object or boolean). Optional liveness endpoint configuration. If omitted, metrics.liveness is used when present.
Example health probes on a standalone server
{
  "metrics": {
    "hostname": "0.0.0.0",
    "port": 9090
  },
  "healthProbes": {
    "hostname": "0.0.0.0",
    "port": 9091,
    "readiness": {
      "endpoint": "/health"
    },
    "liveness": {
      "endpoint": "/live"
    }
  }
}

telemetry​

Open Telemetry is optionally supported with these settings:

  • applicationName (required, string) — Name of the application as will be reported in open telemetry. In the runtime case, the name of the applications as reported in traces is ${applicationName}-${applicationId}, where applicationId is the id of the application in the runtime.
  • version (string) — Optional version (free form)
  • skip (array). Optional list of operations to skip when exporting telemetry defined object with properties:
    • method: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE
    • path. e.g.: /documentation/json
  • exporter (object or array) — Exporter configuration. If not defined, the exporter defaults to console. If an array of objects is configured, every object must be a valid exporter object. The exporter object has the following properties:
    • type (string) — Exporter type. Supported values are console, otlp, zipkin, memory, and file (default: console). memory is only supported for testing purposes.
    • options (object) — These options are supported:
      • url (string) — The URL to send the telemetry to. Required for otlp exporter. This has no effect on console, memory, and file exporters.
      • headers (object) — Optional headers to send with the telemetry. This has no effect on console, memory, and file exporters.
      • path (string) — The path where spans are written when using the file exporter.
      • protocol (string) — OTLP transport protocol. Supported values are http and grpc. Defaults to http.
      • transport (string) — Alias for protocol. Supported values are http and grpc. Defaults to http.
  • diagLogger (boolean) — Enable the OpenTelemetry diagnostic logger. Diagnostic messages are forwarded to the Platformatic global logger using the current logger level.

basePath​

The base path for the Platformatic Runtime. Set it when your application is deployed under a subpath, for example, /api. The runtime will automatically strip the base path from the incoming requests.

important

OTLP traces can be consumed by different solutions, like Jaeger. See the full list here.

For OTLP exporters:

  • Use HTTP with URLs like http://localhost:4318/v1/traces
  • Use gRPC with URLs like http://localhost:4317 and do not include /v1/traces
Example JSON object
{
  "telemetry": {
    "applicationName": "test-application",
    "diagLogger": true,
    "exporter": {
      "type": "otlp",
      "options": {
        "url": "http://localhost:4318/v1/traces"
      }
    }
  }
}

httpCache​

The httpCache configuration is used to enable the HTTP cache for the Platformatic Runtime. It can be a boolean or an object with the following settings:

  • store (string) - The store to use for the cache. Set an npm package name to use a custom store or path to a file to use a custom store from a file. By default, the memory store is used.
  • methods (array) - The HTTP methods to cache. By default, GET and HEAD methods are cached.
  • cacheTagsHeader (string) - The header to use for cache tags.
  • maxCount (integer) - The maximum number of entries in the cache.
  • maxSize (integer) - The maximum size of the cache in bytes.
  • maxEntrySize (integer) - The maximum size of a single entry in the cache in bytes.
  • origins (array) - Whitelist of origins to cache. Only requests to these origins will be cached. Supports exact string matches and regex patterns. To use a regex, wrap the pattern in forward slashes (e.g., "/https:\\/\\/.*\\.example\\.com/").
  • cacheByDefault (integer) - Default cache duration in milliseconds for responses that don't have explicit expiration headers (like Cache-Control or Expires). If not set, responses without explicit expiration will not be cached.
  • type (string) - The type of cache. Can be "shared" (default) or "private". A shared cache may store responses that can be shared between users, while a private cache is dedicated to a single user. Note that s-maxage directive only applies to shared caches, while max-age applies to both.

server​

This configures the Platformatic Runtime entrypoint server.

If the entrypoint has also a server configured, then the runtime settings override the application settings.

An object with the following settings:

  • hostname — Hostname where Platformatic Service server will listen for connections.
  • port — Port where Platformatic Service server will listen for connections. Provide a number or a string. When portAssignment is set to perWorkerIncrement, this is the first port assigned to worker 0.
  • portAssignment (string) — Sets how entrypoint server worker ports are assigned. Default: shared. Set it to shared or leave it unset to make all workers listen on the same port. Set it to perWorkerIncrement to give each worker its own incremental port, starting from port. Use perWorkerIncrement only with external load balancing, never on its own.
  • http2 (boolean) — Enables HTTP/2 support. Default: false.
  • https (object) - Configuration for HTTPS supporting the following options. Requires https.
    • allowHTTP1 (boolean) - If true, the server will also accept HTTP/1.1 connections when http2 is enabled. Default: false.
    • key (required, string, object, or array) - If key is a string, it specifies the private key to be used. If key is an object, it must have a path property specifying the private key file. Multiple keys are supported by passing an array of keys.
    • cert (required, string, object, or array) - If cert is a string, it specifies the certificate to be used. If cert is an object, it must have a path property specifying the certificate file. Multiple certificates are supported by passing an array of keys.

reuseTcpPorts​

Enable the use of the reusePort option whenever any TCP server starts listening on a port. The default is true. This setting can be overridden at the application level.

logger​

This configures the Platformatic Runtime logger, based on pino.

An object with the following settings:

  • level — The log level. Default: info. Valid values are: fatal, error, warn, info, debug, trace, silent.

  • transport — Configuration for logging transport, see pino.transport for more information. Can be configured in two ways:

    • As a single transport: An object with properties:
      • target — A string specifying the transport module.
      • options — An object containing options for the transport.
    • As multiple targets: An object with properties:
      • targets — An array of objects, each with:
        • target — A string specifying the transport module.
        • options — An object containing options for the transport.
        • level — The log level for this specific transport.
      • options — An object containing shared options for all targets.

  • formatters — Configuration for logging formatters. An object with properties:

    • path (required) — A string specifying the path to the formatters; the file exports a function for bindings and level, see pino.formatters for more information.

  • timestamp — The timestamp format to use in logs. Valid values are: epochTime, unixTime, nullTime, isoTime, see pino.timestamp for more information.

  • redact — Configuration for redacting sensitive information, see [pino.redact]https://getpino.io/#/docs/redaction) for more information. An object with properties:

    • paths (required) — An array of strings specifying paths to redact.
    • censor — A string to replace redacted values with. Default: [redacted].

  • captureStdio — If true, the logger will capture the stdout and stderr streams of the main application. Default: false.

  • base — The base logger configuration; setting to null will remove pid and hostname from the logs, otherwise it can be an object to add custom properties to the logs.

  • messageKey — The key to use for the log message. Default: msg.

  • pino — Configures the keys used to recognize Pino log entries emitted by worker applications before wrapping them in stdout or stderr. An object with properties:

    • level — The key that contains the numeric log level. Default: level.
    • time — The key that contains the log timestamp. Default: time.
    • message — The key that contains the log message. Default: msg.

  • customLevels — Configuration for custom levels, see pino.customLevels for more information.

  • openTelemetryExporter — Configuration for exporting logs to OpenTelemetry collectors. When configured alongside the telemetry section, logs are automatically enriched with trace context (trace ID, span ID, trace flags) for correlation with distributed traces. An object with properties:

    • protocol (required) — The protocol to use for export. Valid values are: http, grpc.
    • url (required) — The OTLP collector endpoint URL.

    When used with telemetry configuration, the service name and version from telemetry.applicationName and telemetry.version are automatically included as resource attributes when using getLogger(). See the OpenTelemetry Logging Guide for detailed examples.

undici​

This configures the undici global Dispatcher. Allowing to configure the options in the agent as well as interceptors.

Example JSON object
{
  "undici": {
    "keepAliveTimeout": 1000,
    "keepAliveMaxTimeout": 1000,
    "interceptors": [
      {
        "module": "undici-oidc-interceptor",
        "options": {
          "clientId": "{PLT_CLIENT_ID}",
          "clientSecret": "{PLT_CLIENT_SECRET}",
          "idpTokenUrl": "{PLT_IDP_TOKEN_URL}",
          "origins": ["{PLT_EXTERNAL_SERVICE}"]
        }
      }
    ]
  }
}

It's important to note that IDP stands for Identity Provider, and its token url is the URL that will be called to generate a new token.

applicationTimeout​

The number of milliseconds to wait when invoking another application using the its plt.local before considering the request timed out. Default: 300000 (5 minutes).

messagingTimeout​

The number of milliseconds to wait when invoking another application using the messaging API before considering the request timed out. Default: 300000 (5 minutes).

startupConcurrency​

The maximum number of concurrent operations during runtime startup, including application setup, starting/stopping workers, and health checks. This controls how many applications can be started in parallel.

Default: os.availableParallelism() * 2 (typically twice the number of CPU cores). Minimum: 1.

Setting a lower value can be useful when:

  • Applications have heavy initialization that competes for resources
  • You want more predictable startup ordering
  • Memory is constrained during startup
Example configuration
{
  "startupConcurrency": 4
}

metrics​

This configures the Platformatic Runtime Prometheus server. The Prometheus server exposes aggregated metrics from the Platformatic Runtime applications.

The same server also exposes Kubernetes readiness and liveness probes when healthProbes is enabled without object overrides. If metrics.enabled is false and healthProbes is enabled without object overrides, the server exposes only the probe endpoints. If both metrics.enabled and healthProbes are false, the server is not started.

When healthProbes is an object with a different resolved hostname and port, the Prometheus server follows only the metrics configuration and health probes are exposed on their own server.

  • enabled (boolean or string). If true, the Prometheus server will be started. Default: true.
  • hostname (string). The hostname where the Prometheus server will be listening. Default: 0.0.0.0.
  • port (number). The port where the Prometheus server will be listening. Default: 9090.
  • endpoint (string). The endpoint where the Prometheus server will be listening. Default: /metrics.
  • https (object). Optional configuration for serving the Prometheus, readiness, and liveness endpoints over HTTPS. It supports the same certificate options as server.https:
    • allowHTTP1 (boolean). If true, the server will also accept HTTP/1.1 connections when HTTP/2 is enabled. Default: false.
    • key (required, string, object, or array). A private key as an inline PEM string, an object with a path property pointing to a private key file, or an array of either form.
    • cert (required, string, object, or array). A certificate as an inline PEM string, an object with a path property pointing to a certificate file, or an array of either form.
    • requestCert (boolean). Request a client certificate.
    • rejectUnauthorized (boolean). Reject clients without a valid certificate when requestCert is enabled.
  • auth (object). Optional configuration for the Prometheus server authentication.
    • username (string). The username for the Prometheus server authentication.
    • password (string). The password for the Prometheus server authentication.
  • readiness (object or boolean, default: true). Optional configuration for the Prometheus server readiness checks. If set to true, default readiness checks are enabled. If an object is provided, it can include:
    • endpoint (string). The endpoint for the Prometheus server readiness checks. Default: /ready.
    • success (object). The success criteria for the Prometheus server readiness checks.
      • statusCode (number). The HTTP status code indicating success. Default: 200.
      • body (string). The response body indicating success. Default: OK.
    • fail (object). The failure criteria for the Prometheus server readiness checks.
      • statusCode (number). The HTTP status code indicating failure. Default: 500.
      • body (string). The response body indicating failure. Default: ERR.
  • liveness (object or boolean, default: true). Optional configuration for the Prometheus server liveness checks. If set to true, default liveness checks are enabled. If an object is provided, it can include:
    • endpoint (string). The endpoint for the Prometheus server liveness checks. Default: /status.
    • success (object). The success criteria for the Prometheus server liveness checks.
      • statusCode (number). The HTTP status code indicating success. Default: 200.
      • body (string). The response body indicating success. Default: OK.
    • fail (object). The failure criteria for the Prometheus server liveness checks.
      • statusCode (number). The HTTP status code indicating failure. Default: 500.
      • body (string). The response body indicating failure. Default: ERR.
  • healthChecksTimeouts: Deprecated. This setting is accepted for compatibility but is no longer used.
  • plugins (array of string): A list of Fastify plugin to add to the Prometheus server.
  • applicationLabel (string, default: 'applicationId'): The label name to use for the application identifier in metrics (e.g., 'applicationId', 'serviceId', or any custom label name).
  • httpClientMetrics (boolean or string, default: false): Enable outgoing HTTP client request duration metrics (http_client_request_duration_seconds). This metric includes labels for the method, status code, dispatcher URL, and error type.
  • timeout (number, default: 10000): The timeout to wait for each worker metrics before skipping it.
  • httpCustomLabels (array of object): Custom labels to add to HTTP metrics (http_request_all_duration_seconds and http_request_all_summary_seconds). Each label extracts its value from an HTTP request header. By default, no custom labels are added. Each object supports:
    • name (required, string): The label name to use in metrics.
    • header (required, string): The HTTP request header to extract the value from.
    • default (string): Default value when the header is missing. Defaults to "unknown".
Example httpCustomLabels Configuration
{
  "metrics": {
    "enabled": true,
    "httpCustomLabels": [{ "name": "callerTelemetryId", "header": "x-plt-telemetry-id", "default": "" }]
  }
}
  • otlpExporter (object): Optional configuration for exporting Prometheus metrics to an OpenTelemetry Protocol (OTLP) endpoint. This enables pushing metrics to OTLP-compatible collectors like OpenTelemetry Collector, Grafana Cloud, or other observability platforms. The object supports the following settings:
    • enabled (boolean or string): Enable or disable OTLP metrics export. Default: true if endpoint is configured.
    • endpoint (required, string): OTLP endpoint URL for metrics (e.g., http://localhost:4318/v1/metrics).
    • interval (number or string): Interval in milliseconds between metric pushes. Default: 60000 (60 seconds).
    • headers (object): Additional HTTP headers for authentication or custom metadata. Common use cases include API keys or authentication tokens.
    • serviceName (string): Service name for OTLP resource attributes. Defaults to the application ID.
    • serviceVersion (string): Service version for OTLP resource attributes. Optional.
Example OTLP Metrics Configuration
{
  "metrics": {
    "enabled": true,
    "port": 9090,
    "otlpExporter": {
      "endpoint": "http://otel-collector:4318/v1/metrics",
      "interval": 30000,
      "headers": {
        "x-api-key": "{OTLP_API_KEY}"
      },
      "serviceName": "my-platformatic-app",
      "serviceVersion": "1.0.0"
    }
  }
}

If the metrics object is not provided, the Prometheus server will not be started.

managementApi​

Warning: Experimental. The feature is not subject to semantic versioning rules. Non-backward compatible changes or removal may occur in any future release. Use of the feature is not recommended in production environments.

An optional object that configures the Platformatic Management Api. If this object is not provided, the Platformatic Management Api will be started by default. If enabled, it will listen to UNIX Socket/Windows named pipe located at platformatic/pids/<PID> inside the OS temporary folder.

  • logs (object). Optional configuration for the runtime logs.
    • maxSize (number). Maximum size of the logs that will be stored in the file system in MB. Default: 200. Minimum: 5.
  • socket (string). Optional custom path for the control socket. If not specified, the default platform-specific location is used (platformatic/runtimes/<PID>/socket on Unix, \\.\pipe\platformatic-<PID> on Windows).

management​

The runtime-level management configuration enables the ITC (Inter-Thread Communication) management client for all applications in the runtime. This is particularly useful for single-app deployments where you want every worker to have access to management operations without specifying management on each individual application.

The value is inherited by all applications that do not explicitly set their own management configuration. Individual applications can override or disable the runtime-level setting.

Enable management for all applications
{
  "management": true,
  "applications": [
    {
      "id": "app1",
      "path": "./services/app1"
    },
    {
      "id": "app2",
      "path": "./services/app2"
    }
  ]
}
Enable management globally, disable for a specific application
{
  "management": true,
  "applications": [
    {
      "id": "orchestrator",
      "path": "./services/orchestrator"
    },
    {
      "id": "worker",
      "path": "./services/worker",
      "management": false
    }
  ]
}
Restrict operations globally
{
  "management": {
    "operations": ["getRuntimeStatus", "getApplicationsIds"]
  },
  "applications": [
    {
      "id": "app1",
      "path": "./services/app1"
    }
  ]
}

The configuration format is the same as the per-application management setting (boolean or object with enabled and operations). See the per-application management section for the full list of available operations.

scheduler​

An optional array of objects to configure HTTP call triggered by cron jobs. Every object has:

  • enabled (boolean or string). Optional. If false the scheduler is disabled. Default: true.
  • name (string): The job name
  • cron (string): the crontab schedule expession. See https://crontab.guru/examples.html for some examples.
  • callbackUrl (string): the HTTP URL to be called
  • method (string): Optional, can be GET, POST, PUT, PATCH, DELETE. Default: GET.
  • body (string or object). Optional.
  • headers (object). Optional. Headers added to the HTTP call.
  • maxRetry (number). Number of attempts for the HTTP call. Default: 3
Example Scheduler
{
  "scheduler": [
    {
      "name": "test",
      "callbackUrl": "http://mytarget",
      "cron": "0 * * * *",
      "mehod": "GET"
    }
  ]
}

verticalScaler​

warning

The verticalScaler configuration is deprecated and will be removed in a future version. These options are now mapped to the equivalent properties in the workers configuration. Please use the workers configuration instead.

The verticalScaler configuration is used to enable the vertical scaling for the Platformatic Runtime. The vertical scaler automatically adjusts the number of workers for each application based on Event Loop Utilization (ELU) and available system memory.

The scaler operates in two modes:

  • Reactive Mode: Triggers scaling checks immediately when any worker's ELU exceeds the scaleUpELU threshold
  • Periodic Mode: Runs scaling checks at regular intervals defined by scaleIntervalSec

When scaling up, the algorithm ensures there is sufficient available memory to accommodate new workers based on the application's average heap usage. Available memory is calculated as maxTotalMemory - currently used memory, where used memory is obtained from cgroup files in containerized environments or from the operating system otherwise.

Configuration options:

  • enabled (boolean or string). If false the vertical scaling is disabled. Default: true.
  • maxTotalWorkers (number). The maximum number of workers that can be used for all applications. Default: os.availableParallelism() (typically the number of CPU cores).
  • maxTotalMemory (number). The maximum total memory in bytes that can be used by all workers. Default: 90% of the system's total memory.
  • minWorkers (number). The minimum number of workers that can be used for each application. It can be overridden at application level. Default: 1.
  • maxWorkers (number). The maximum number of workers that can be used for each application. It can be overridden at application level. Default: global maxTotalWorkers value.
  • cooldownSec (number). The amount of seconds the scaling algorithm will wait after making a change before scaling up or down again. This prevents rapid oscillations. Default: 60.
  • scaleUpELU (deprecated, number). This property is deprecated and currently unused. The ELU threshold for scaling up is hardcoded to 0.8.
  • scaleDownELU (deprecated, number). This property is deprecated and currently unused. The ELU threshold for scaling down is hardcoded to 0.2.
  • timeWindowSec (deprecated, number). This property is deprecated and currently unused. The time window for scale-up decisions is hardcoded to 10 seconds.
  • scaleDownTimeWindowSec (deprecated, number). This property is deprecated and currently unused. The time window for scale-down decisions is hardcoded to 60 seconds.
  • gracePeriod (number). The amount of milliseconds after a worker is started before the scaling algorithm will start collecting metrics for it. This allows workers to stabilize after startup. Default: 30000.
  • scaleIntervalSec (deprecated, number). This property is deprecated and currently unused. The interval for periodic scaling checks is hardcoded to 60 seconds.
  • applications (object). An object with application-specific scaling configuration. Each key is an application ID, with an object value containing:
    • minWorkers (number). The minimum number of workers that can be used for this application. Default: 1.
    • maxWorkers (number). The maximum number of workers that can be used for this application. Default: global maxWorkers value.

Notes:

  • Applications with a fixed workers configuration or entrypoint applications on systems without reusePort support will have their min/max workers automatically set to their current value to prevent scaling.
  • The scaler tracks heap memory usage and will not scale up if there is insufficient available memory, even if ELU thresholds are met.
  • By default, the scaler uses 90% of total system memory as the memory limit to provide a safety buffer and prevent out-of-memory situations.

policies​

The policies configuration is used to define security policies that control communication between applications in the runtime. The security model follows an "allow by default" approach, meaning all inter-application communication is permitted unless explicitly restricted.

Configuration options:

  • deny (object). An object that defines communication restrictions between applications. The key is the source application ID, and the value is the target application ID that should be blocked (the value can also be an array of IDs). The blocking is bidirectional. For example, denying communication from application-1 to application-2 will also automatically block communication from application-2 to application-1.

When policies are configured, fetch requests or messaging API calls between blocked application will throw an exception.

compileCache​

The compileCache configuration enables Node.js module compile cache to improve application startup performance. When enabled, V8 compiled code is stored on disk and reused on subsequent starts, significantly reducing startup time for applications with many dependencies.

note

This feature requires Node.js 22.1.0 or later. On older Node.js versions, this configuration is silently ignored.

The configuration can be a boolean or an object:

Simple boolean configuration
{
  "compileCache": true
}
Object configuration
{
  "compileCache": {
    "enabled": true,
    "directory": ".plt/compile-cache"
  }
}

Configuration options:

  • enabled (boolean). Enable or disable the compile cache. Default: true when the object form is used.
  • directory (string). The directory to store the compile cache. Default: .plt/compile-cache relative to the application root.

Performance considerations:

  • First run: The initial startup may be slightly slower as the cache is populated.
  • Subsequent runs: Startup time is significantly reduced as compiled code is loaded from the cache.
  • Disk space: The cache grows with the size of your codebase and dependencies.

Limitations:

  • Code coverage: V8 coverage precision may be reduced for cached functions. Disable compile cache when running coverage tests.
  • Node.js version changes: The cache is automatically invalidated when the Node.js version changes.

This configuration can also be set at the application level to override the runtime-level setting:

Application-level override
{
  "applications": [
    {
      "id": "my-app",
      "path": "./services/my-app",
      "compileCache": {
        "enabled": false
      }
    }
  ]
}

management​

The management per-application configuration grants an application access to runtime management operations directly through the ITC (Inter-Thread Communication) channel. This allows orchestrator-style applications to list services, restart applications, inspect configuration, proxy requests, and more — without requiring the HTTP-based managementApi to be enabled.

When enabled, a ManagementClient instance is available via getManagement() inside the application worker. Applications without management enabled have no access to these operations.

This setting can also be configured at the runtime level to apply to all applications at once.

The configuration can be a boolean or an object:

Grant full management access
{
  "applications": [
    {
      "id": "orchestrator",
      "path": "./services/orchestrator",
      "management": true
    }
  ]
}
Restrict to specific operations
{
  "applications": [
    {
      "id": "dashboard",
      "path": "./services/dashboard",
      "management": {
        "operations": ["getRuntimeStatus", "getApplicationsIds", "getApplicationDetails"]
      }
    }
  ]
}

Configuration options (object form):

  • enabled (boolean). Enable or disable management access. Default: true when the object form is used.
  • operations (array of strings). An optional whitelist of allowed operations. If omitted, all operations are available.

Available operations:

OperationDescription
getRuntimeStatusGet the current runtime status
getRuntimeMetadataGet runtime metadata (pid, versions, uptime)
getRuntimeConfigGet the runtime configuration
getRuntimeEnvGet the runtime environment variables
getApplicationsIdsList all application IDs
getApplicationsGet details for all applications
getWorkersGet worker thread information
getApplicationDetails(id)Get details for a specific application
getApplicationConfig(id)Get an application's configuration
getApplicationEnv(id)Get an application's environment variables
getApplicationOpenapiSchema(id)Get an application's OpenAPI schema
getApplicationGraphqlSchema(id)Get an application's GraphQL schema
getMetrics(format)Get runtime metrics
startApplication(id)Start an application
stopApplication(id)Stop an application
restartApplication(id)Restart an application
restart(applications)Restart selected applications
addApplications(applications, start)Dynamically add applications
removeApplications(ids)Remove applications
inject(id, injectParams)Proxy an HTTP request to another application

Usage example inside a privileged application:

Use getManagement() from @platformatic/globals to access the management API.

import { getManagement } from '@platformatic/globals'

export function create () {
  const app = fastify()
  const management = getManagement()

  app.get('/services', async () => {
    const { applications } = await management.getApplications()
    return applications
  })

  app.post('/services/:id/restart', async req => {
    await management.restartApplication(req.params.id)
    return { ok: true }
  })

  app.get('/proxy/:id/*', async req => {
    const { id, '*': url } = req.params
    return management.inject(id, {
      method: 'GET',
      url: '/' + url
    })
  })

  return app
}

Setting and Using ENV placeholders​

The value for any configuration setting can be replaced with an environment variable by adding a placeholder in the configuration file, for example {PLT_ENTRYPOINT}.

If an .env file exists it will automatically be loaded by Platformatic using dotenv. For example:

.env
PLT_ENTRYPOINT=application

The .env file must be located in the same folder as the Platformatic configuration file or in the current working directory. Each application would also see their respective .env file loaded if they are located in a subdirectory. This can be configured by the envfile property in the application configuration.

Environment variables can also be set directly on the command line, for example:

PLT_ENTRYPOINT=application npx wattpm start
note

Learn how to set and use environment variable placeholders documentation.

PLT_ROOT​

The {PLT_ROOT} placeholder is automatically set to the directory containing the configuration file, so it can be used to configure relative paths. See our documentation to learn more on PLT_ROOT placeholders.

Issues

If you run into a bug or have a suggestion for improvement, please raise an issue on GitHub or join our Discord feedback channel.