Choose the Assistant model & behavior

The model is the engine behind every Assistant reply. ModuleX lets you run the Assistant on a managed model (provisioned by ModuleX and billed in credits) or on a BYOK model (your own provider account, billed by the provider with no ModuleX markup). This page shows you how to choose, what each choice costs, what is available to your organization, and how a chat’s settings behave. If you are new to the Assistant, start with the Assistant overview. For how the Assistant uses tools and pauses for approval, see Using tools and Human-in-the-loop.

The Assistant shares its model picker and provider catalog with the rest of ModuleX. The same managed-vs-BYOK choice applies in the chat surface and the workflow Composer. Connect and manage providers once on the LLM providers page.

The two ways to run the Assistant

Managed models

ModuleX provisions the model for you. Nothing to connect — it works the moment you open a chat. Usage is metered in credits. The managed provider’s name on the wire is modulexai.

BYOK — bring your own key

Connect your own OpenAI, Anthropic, Google Gemini, or xAI account. The model provider bills you directly with no ModuleX markup, and the usage is not charged in credits.

How they compare

	Managed (`modulexai`)	BYOK
Setup	None — available by default	Connect a provider credential first
Who bills you	ModuleX, in credits	The provider, directly
ModuleX markup	Priced in credits (`100 credits = $1.00`)	None
Counts toward your credit limit	Yes	No — tracked for analytics only
Providers	ModuleX-provisioned models	OpenAI, Anthropic, Google Gemini, xAI

Use managed models to get started with zero setup and predictable in-app billing. Switch to BYOK when you already have provider accounts, want to use a specific model, or want provider billing to stay outside your ModuleX credit budget. See Credits & metering for what a credit is.

Choose a model in the app

Open or start an Assistant chat

Go to the chat surface and open a new Assistant chat or an existing one. See the Chat overview for the full surface.

Open the model picker

The model selector sits in the chat. It lists the managed model first, then each provider your organization has connected.

Pick a model

Select a managed model for credit-based billing, or a model under a connected BYOK provider to bill through that provider. Your choice applies to the next turn you send.

Send your message

The Assistant runs on the selected model. Every turn records which model actually served the request, so usage and any credit charges are attributed to the served model.

What happens if you do not pick a model

If you do not choose a model, the Assistant uses your organization’s default model. ModuleX resolves the default like this:

Your organization's saved default

If an owner or admin has saved a default model in organization settings, that model is used.

A managed fallback

If no default is saved, ModuleX falls back to the first available managed (modulexai) model. This keeps brand-new and legacy organizations working without anyone configuring a model first.

A saved default is stored as settings.composer_llm on the organization and is shared by the Assistant and the workflow Composer. Setting or clearing it requires the owner or admin role (see Permissions & limits).

Per-organization model availability

The models you can pick are scoped to your organization. Two things determine what shows up in the picker.

Managed models — always available

The managed modulexai provider is provisioned for every organization, so at least one managed model is always selectable. This is what powers the fallback default.

BYOK models — only when connected

A BYOK provider’s models appear only after someone in your organization connects a credential for that provider. No credential means no models from that provider in the picker.

To make a BYOK provider available to your whole organization, connect its credential once on the LLM providers page. Connected credentials are organization-scoped, so every member who can use the Assistant sees the same provider list. For how credentials are stored and resolved, see Credentials & OAuth2 and Managing credentials.

Only organization owners and admins can use the Assistant today. The member role has been retired for Assistant, Composer, and schedules. If a teammate cannot open the Assistant, check their role — see Roles & permissions and Organizations, roles & membership.

When a model is retired or unavailable

Managed model catalogs change over time. ModuleX handles this for you so a chat does not break:

Deprecated or in-maintenance managed models

If a managed model is marked deprecated or in maintenance, ModuleX routes your request to its replacement model automatically. Usage and any credit charge are recorded against the model that actually served the turn, not the one you requested.

An unknown managed model id

If a requested managed model id can’t be resolved, ModuleX softens to the managed provider’s default serving model rather than failing the turn.

BYOK models

BYOK providers pass your model choice straight through to the provider — ModuleX does not rewrite it. If the provider no longer serves that model, the provider returns the error so you see it directly. Pick a current model from your provider, or reconnect the provider on the LLM providers page.

How the model is sent on a turn

When the app sends a turn to the Assistant, the model choice travels as an llm object. You will see the same object if you drive the Assistant from the API or an SDK. It has these fields:

Field	Required	What it is
`integration_name`	Yes	The provider, e.g. `modulexai` for managed, or `openai` / `anthropic` / `gemini` / `xai` for BYOK.
`provider_id`	Yes	The provider’s id for the model.
`model_id`	Yes	The model to run, e.g. `gpt-4o`.
`credential_id`	No	A specific connected credential to use for this turn.

If the llm object is omitted entirely, ModuleX applies your organization’s default as described above. If it is present but missing any required field, the request is rejected with a 400 validation error. Validation errors use the {detail} envelope — see Errors & status codes.

curl -X POST https://api.modulex.dev/assistant/chat \
  -H "Authorization: Bearer mx_live_a1b2c3d4e5f6a7b8c9d0e1f2" \
  -H "X-Organization-ID: org_8e7d6c5b4a39281706f5e4d3" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize the latest commit on my main branch",
    "llm": {
      "integration_name": "openai",
      "provider_id": "openai",
      "model_id": "gpt-4o"
    }
  }'

from modulex import Modulex

client = Modulex(
    api_key="mx_live_a1b2c3d4e5f6a7b8c9d0e1f2",
    organization_id="org_8e7d6c5b4a39281706f5e4d3",
)

response = client.assistant.chat(
    message="Summarize the latest commit on my main branch",
    llm={
        "integration_name": "openai",
        "provider_id": "openai",
        "model_id": "gpt-4o",
    },
)
print(response["stream_url"])

import { Modulex } from "modulex-js";

const client = new Modulex({
  apiKey: "mx_live_a1b2c3d4e5f6a7b8c9d0e1f2",
  organizationId: "org_8e7d6c5b4a39281706f5e4d3",
});

const response = await client.assistant.chat({
  message: "Summarize the latest commit on my main branch",
  llm: {
    integration_name: "openai",
    provider_id: "openai",
    model_id: "gpt-4o",
  },
});
console.log(response.stream_url);

Every Assistant request authenticates with Authorization: Bearer mx_live_… plus the X-Organization-ID header. The provider keys for a BYOK model are your connected credentials — they are never put in the request body. See Authentication.

To run the Assistant on a managed model from code, set integration_name to modulexai and use a managed provider_id / model_id from the ModuleX-managed models catalog. Omit llm to let ModuleX apply the organization default.

Behavior settings

Beyond the model, a few settings shape how the Assistant works in a chat.

One question at a time

The Assistant can pause to ask you something or to confirm an action before it runs. A chat holds only one pending question at a time — answer or cancel it before sending a new message. If you try to send while a question is open, ModuleX asks you to answer it first. See Human-in-the-loop.

Approval before write actions

For actions that change or delete data in a connected service, the Assistant shows a “Run this?” approval card and waits for you to approve or cancel. Read-only lookups run without an approval step. Learn more in Using tools.

Stop a running reply

You can stop an in-progress turn at any time. Stopping cancels the current run; you can then send a new message. The model and provider settings you picked stay in place.

Streaming responses

The Assistant streams its thinking, tool steps, and text as it works, so you see progress live rather than waiting for a final answer. See Streaming responses.

The Assistant v1 is text-only — each turn is a single text message. Picking a model does not enable image or audio input in the Assistant chat. (Voice input is a separate chat feature — see Voice messages.)

What your model choice costs

How a turn is billed depends on which kind of model you picked.

Managed model turns

Run on credits. ModuleX checks your plan and credit balance before the turn starts, then records token usage as the turn completes. If your plan credits and wallet are exhausted, the turn is refused before any work happens.

BYOK model turns

Billed by your provider, not in credits. ModuleX still tracks the usage for your analytics, but it does not count against your credit limit.

Because every Assistant turn passes through the billing admission gate, a managed turn can be refused with a 402, 403, or 429 when credits, plan quota, or rate limits are reached. These denials use the flat {code, layer, key, current, limit, reason} envelope — see Usage gating & limits and Errors & status codes. For who can use the Assistant and the limits that apply, see Permissions & limits.

Switching to a BYOK model does not remove the per-turn rate limit or the requirement to be an owner or admin — it only changes who pays for the model tokens.

LLM providers

Connect and manage managed and BYOK model providers.

Model selection in chat

The same model picker, across the chat surface.

ModuleX-managed models

The default managed provider, billed in credits.

Permissions & limits

Who can use the Assistant and the limits that apply.

Streaming responses

Watch the Assistant work in real time.

Credits & metering

What a credit is and what consumes them.

App overview

Chat

Knowledge

Collaboration

Builder

Nodes

Execution

Co-editing

Assistant Chat

Choose the Assistant model & behavior

The two ways to run the Assistant

Managed models

BYOK — bring your own key

How they compare

Choose a model in the app

What happens if you do not pick a model

Per-organization model availability

Managed models — always available

BYOK models — only when connected

When a model is retired or unavailable

How the model is sent on a turn

Behavior settings

What your model choice costs

Managed model turns

BYOK model turns

LLM providers

Model selection in chat

ModuleX-managed models

Permissions & limits

Streaming responses

Credits & metering

​The two ways to run the Assistant

Managed models

BYOK — bring your own key

​How they compare

​Choose a model in the app

​What happens if you do not pick a model

​Per-organization model availability

Managed models — always available

BYOK models — only when connected

​When a model is retired or unavailable

​How the model is sent on a turn

​Behavior settings

​What your model choice costs

Managed model turns

BYOK model turns

​Related pages

LLM providers

Model selection in chat

ModuleX-managed models

Permissions & limits

Streaming responses

Credits & metering

The two ways to run the Assistant

How they compare

Choose a model in the app

What happens if you do not pick a model

Per-organization model availability

When a model is retired or unavailable

How the model is sent on a turn

Behavior settings

What your model choice costs

Related pages