Configuration

app.create() takes a single options object: the components you want to register plus a config object of type ExuluConfig. This page documents every option, verified against the current @exulu/backend source.

create() options

await app.create({
  config,        // ExuluConfig — required
  contexts,      // Record<string, ExuluContext>
  providers,     // ExuluProvider[]
  agents,        // ExuluAgent[]
  tools,         // ExuluTool[]
  evals,         // ExuluEval[]
});

config

ExuluConfig

required

Platform configuration. workers and MCP are required fields inside it; everything else is optional. See the full reference below.

contexts

Record<string, ExuluContext>

Map of context key to ExuluContext instance. IMP merges its built-in contexts (currently transcriptions) after yours, so a built-in wins on key collision — a warning is logged if you define a context under the key transcriptions.

providers

ExuluProvider[]

Custom model providers, appended after the 19 built-in defaults. See ExuluProvider.

agents

ExuluAgent[]

Code-defined agents. Agents can also be created in the database through the platform UI; app.agent() and app.agents() read from both. Code-defined agents without an explicit RBAC block default to public access.

tools

ExuluTool[]

Custom tools, registered ahead of the built-in todo, question, Perplexity, email, and image-generation tools. See ExuluTool.

evals

ExuluEval[]

Custom evaluations, merged with the built-in LLM-as-judge eval. Evals require Redis (REDIS_HOST + REDIS_PORT); without it, no evals are registered — including the ones you pass here.

Every context, tool, and provider ID must start with a letter or underscore, contain only letters, digits, and underscores, and be at most 80 characters. Treat 5 characters as the practical minimum — the runtime error message enforces intent at 5, though the current validator accepts shorter IDs; don’t rely on that. create() throws on the first violation.

ExuluConfig reference

type ExuluConfig = {
  workers: {
    enabled: boolean;
    logger?: { winston: { transports: transport[] } };
    telemetry?: { enabled: boolean };
  };
  MCP: {
    enabled: boolean;
  };
  telemetry?: {
    enabled: boolean;
  };
  logger?: {
    winston: { transports: transport[] };
  };
  fileUploads?: {
    s3region: string;
    s3key: string;
    s3secret: string;
    s3Bucket: string;
    s3endpoint?: string;
    s3prefix?: string;
  };
  privacy?: {
    systemPromptPersonalization?: boolean;
  };
  requireSystemDependencies?: boolean;
};

Both workers and MCP are required top-level fields. All others are optional.

Workers

workers.enabled

boolean

required

Declare whether this deployment runs a worker process. The workers themselves start only when you call app.bullmq.workers.create() in a separate process.

workers.logger.winston.transports

winston.transport[]

Winston transports used by the worker process. Falls back to logger.winston.transports, and finally to a built-in console transport (colorized with timestamps in development, JSON in production).

workers.telemetry.enabled

boolean

default:"false"

Enable OpenTelemetry tracing and log forwarding in the worker process. Independent of the server-side telemetry.enabled.

import winston from "winston";

const config = {
  workers: {
    enabled: true,
    logger: {
      winston: {
        transports: [
          new winston.transports.File({ filename: "logs/workers.log" }),
        ],
      },
    },
    telemetry: { enabled: true },
  },
  MCP: { enabled: false },
};

Workers require Redis (REDIS_HOST / REDIS_PORT) and an Enterprise Edition license (EXULU_ENTERPRISE_LICENSE). app.bullmq.workers.create() throws if the license is absent or invalid.

MCP

MCP.enabled

boolean

required

When true, app.express.init() mounts a Model Context Protocol server on the Express application. Each agent becomes reachable as a streamable-HTTP MCP endpoint at /mcp/:agent, so external MCP clients can call your agents with their registered tools and contexts.

const config = {
  workers: { enabled: false },
  MCP: { enabled: true },
};

Telemetry

telemetry.enabled

boolean

default:"false"

Enable OpenTelemetry tracing for the Express server. Traces and logs are exported to the collector configured through your OTEL environment variables.

const config = {
  workers: { enabled: true },
  MCP: { enabled: false },
  telemetry: { enabled: process.env.NODE_ENV === "production" },
};

Logging

logger.winston.transports

winston.transport[]

Winston transports for the server process. When omitted, IMP uses a console transport: colorized with HH:mm:ss timestamps in development, JSON in production. Log messages longer than 50 lines are truncated with a (… more lines omitted) marker.

import winston from "winston";

const config = {
  workers: { enabled: true },
  MCP: { enabled: false },
  logger: {
    winston: {
      transports: [
        new winston.transports.Console({ format: winston.format.json() }),
        new winston.transports.File({ filename: "logs/server.log" }),
      ],
    },
  },
};

IMP routes console.log, console.info, console.warn, console.error, and console.debug through the configured Winston logger, so all output — including from your own code — flows through your transports.

File uploads

S3-compatible object storage for chat attachments, knowledge files, and generated images. All four core fields are required together.

fileUploads.s3region

string

required

Region of the bucket, for example us-east-1.

fileUploads.s3key

string

required

Access key ID.

fileUploads.s3secret

string

required

Secret access key.

fileUploads.s3Bucket

string

required

Bucket name.

fileUploads.s3endpoint

string

Custom endpoint URL for S3-compatible services such as MinIO. Omit for AWS S3.

fileUploads.s3prefix

string

Key prefix applied to uploaded objects.

const config = {
  workers: { enabled: true },
  MCP: { enabled: false },
  fileUploads: {
    s3region: "us-east-1",
    s3key: process.env.COMPANION_S3_KEY!,
    s3secret: process.env.COMPANION_S3_SECRET!,
    s3Bucket: "exulu-uploads",
    s3endpoint: "http://localhost:9000",
  },
};

const config = {
  workers: { enabled: true },
  MCP: { enabled: false },
  fileUploads: {
    s3region: process.env.COMPANION_S3_REGION!,
    s3key: process.env.COMPANION_S3_KEY!,
    s3secret: process.env.COMPANION_S3_SECRET!,
    s3Bucket: process.env.COMPANION_S3_BUCKET!,
    s3prefix: "uploads/",
  },
};

The image-generation widget tool is only registered when both LiteLLM (EXULU_USE_LITELLM=true) and this fileUploads block are configured, because generated images are stored in S3.

Privacy

privacy.systemPromptPersonalization

boolean

Controls whether user-specific personalization is injected into agent system prompts. When disabled, all users receive the same system prompts.

const config = {
  workers: { enabled: true },
  MCP: { enabled: false },
  privacy: { systemPromptPersonalization: false },
};

System dependencies

requireSystemDependencies

boolean

default:"true"

IMP probes for the pandoc, soffice (LibreOffice), and pdftoppm (Poppler) binaries and the globally installed docx npm package — all needed by the built-in document skills. By default (unset or true), create() throws when any is missing, so misconfigured production images fail fast. Set to false to log a warning instead; skills that need the missing dependency then fail at use time.

const config = {
  workers: { enabled: true },
  MCP: { enabled: false },
  requireSystemDependencies: process.env.NODE_ENV === "production",
};

Complete example

import { ExuluApp, type ExuluConfig } from "@exulu/backend";
import winston from "winston";

const config: ExuluConfig = {
  workers: {
    enabled: true,
    telemetry: { enabled: true },
  },
  MCP: { enabled: true },
  telemetry: { enabled: process.env.NODE_ENV === "production" },
  logger: {
    winston: {
      transports: [
        new winston.transports.Console({ format: winston.format.json() }),
      ],
    },
  },
  fileUploads: {
    s3region: process.env.COMPANION_S3_REGION!,
    s3key: process.env.COMPANION_S3_KEY!,
    s3secret: process.env.COMPANION_S3_SECRET!,
    s3Bucket: process.env.COMPANION_S3_BUCKET!,
    s3endpoint: process.env.COMPANION_S3_ENDPOINT,
  },
  privacy: { systemPromptPersonalization: false },
  requireSystemDependencies: process.env.NODE_ENV === "production",
};

export const app = new ExuluApp();
export const ready = app.create({
  config,
  contexts: {},
  tools: [],
});

Environment variables referenced by the platform at runtime (Postgres, Redis, NextAuth, LiteLLM) are documented in Environment variables.

create() options

ExuluConfig reference

Workers

MCP

Telemetry

Logging

File uploads

Privacy

System dependencies

Complete example

Next steps

API reference

ExuluContext

​create() options

​ExuluConfig reference

​Workers

​MCP

​Telemetry

​Logging

​File uploads

​Privacy

​System dependencies

​Complete example

​Next steps

API reference

ExuluContext

create() options

ExuluConfig reference

Workers

MCP

Telemetry

Logging

File uploads

Privacy

System dependencies

Complete example

Next steps