nola.config.ts

Create nola.config.ts at your project root and default-export a defineConfig({...}) call. Set model to one model or a named map with a default entry. Every other setting is optional.

To use the Nola platform, set model: "nola". To send traces to a local Nola console, add telemetry: "http://127.0.0.1:4141". These strings are shorthand for the nola factories: nola.infer() and nola.tracer(url). Use the factories when you need to pass options.

// nola.config.ts — Nola serves inference
import { defineConfig } from "@nola-lang/runtime";

export default defineConfig({
  // Reads NOLA_API_KEY from the environment at the first ask.
  model: "nola",
});

// nola.config.ts — bring your own model
import { openai } from "@nola-lang/providers";
import { defineConfig } from "@nola-lang/runtime";

export default defineConfig({
  // Reads OPENAI_API_KEY from the environment at the first ask.
  model: openai({ model: "gpt-5-mini" }),
});

The import surface is frozen

Configuration imports come from two packages:

import { defineConfig, nola, terminalTrace } from "@nola-lang/runtime";
import { openai, mockProvider, withRetry } from "@nola-lang/providers";

Import defineConfig, terminalTrace and the nola namespace from @nola-lang/runtime.

Import vendor factories (openai, anthropic, google, mockProvider), resilience helpers (withRetry, fallback, roundRobin, constant, exponential) and record/replay from @nola-lang/providers.

Use the package imports shown above. Subpaths such as @nola-lang/runtime/config, @nola-lang/runtime/providers and nola-lang/runtime do not exist. The providers package has no runtime dependency, which helps avoid installing a second copy of the runtime.

Validated and frozen

Nola validates and freezes the config when it loads. An unknown top-level key or a model map without default produces NOLA3003; the message names the file and field. The reserved plugins key produces NOLA3005.

You can configure the runtime before the first ask. After that, reconfiguration is an error. Tests can call nolaRuntime.reset() to start again. See Config schema for each setting’s type, default and current support.

How it reaches run time

• nola run / node --import nola-lang/register load the project-root .env, bundle and evaluate nola.config.ts, then configure the process before your entry runs.
• nola build bundles the config into dist/nola.config.js for app projects, the default build target. Each built .tsi.js module imports that config, so it runs under plain node without manual setup. The command compiles .tsi files only; see Deploying for the entry-point setup.
• build.target: "lib" skips config bundling. The app that consumes the library supplies the config.
• Bundler plugins (@nola-lang/vite, webpack, rollup, rolldown, esbuild, rspack and @nola-lang/next) include the config in the server bundle. See The nola CLI and the plugin READMEs on npm.

Rules

• The config cannot import .tsi modules — it is evaluated before the Nola loader registers (NOLA3012).
• Keep compiler.underivableContextType a literal value: the editor reads it statically and cannot execute your config.
• Secrets come from the environment (.env in development, the real environment in production) — never inline keys. See Environments and secrets.

Section map

Key	What it does	Page
model	one model, or a named map with a required default; "nola" is the platform	Models and providers
project	names this app in traces and platform requests; defaults to the package.json name	Config schema
forceModel	sends every ask to the named model	Models and providers
telemetry	the observer list — terminal, tracers, your observers, receipts	Telemetry
ask, system	per-invocation timeout, extra system text	Ask options
compiler, build	underivableContextType; build.target	Config schema
middleware, cache	accepted and validated, but currently have no effect	Config schema
plugins	reserved — rejected at load	—

Next: Providers