How to Use a Custom LLM Provider with Self-Hosted n8n Assistant

Introduction

Self-hosted n8n Assistant can build, explain, and fix workflows from a plain-language prompt, but it does not ship with a model of its own. On a self-hosted instance, you choose the provider, you hold the API key, and your provider bills the tokens. That freedom is useful when your team already standardizes on one provider, when a flagship model is too expensive for everyday drafting, or when a local model keeps prompts inside your own network. This tutorial shows the two documented routes: a supported provider such as OpenRouter, and a direct OpenAI-compatible endpoint for a local or third-party server. You will also learn how to switch models without losing the Assistant, how to test a new model fairly, and how to keep costs under control.

Quick answer

Set the model in provider/model form, add its API key, and restart n8n. For a direct custom endpoint, also set N8N_INSTANCE_AI_MODEL_URL to its /v1 address, with a sandbox already running.

Evidence

The official setup guide states the requirement plainly: every self-hosted n8n Assistant setup needs three things, a model provider, a sandbox, and optionally a search provider. The guide also gives the pricing boundary in one sentence that every self-hosted user should remember: “n8n does not provide the model. You bring your own API key, and model usage is billed directly by your provider.” That sentence, from the n8n announcement for self-hosted Assistant in version 2.35, explains why a model switch is a billing decision as well as a quality decision.

Two named numbers from the official documentation help you plan the setup. First, the default Assistant model is anthropic/claude-opus-4-8. Second, with Daytona as the managed sandbox, n8n stops an idle sandbox after 15 minutes, archives a stopped sandbox after one hour, and deletes it after seven days. Those defaults, in the official guide to setting up n8n Assistant, matter because a change that looks broken may be a cold sandbox starting again. The same guide lists Anthropic, OpenAI, and OpenRouter as supported providers, and documents the custom endpoint variable separately.

Prerequisites

• A self-hosted n8n instance on version 2.35 or later, installed with Docker. The one-line setup guide is the simplest path for a new instance, because it starts the bundled sandbox and search services alongside n8n.
• Access to edit the instance’s environment file, usually ./n8n/.env for a one-line install, and permission to restart the n8n container.
• A sandbox that is already running. For local testing, the bundled sandbox from the one-line setup or the Docker Compose guide is enough. For production, use Daytona, as n8n recommends.
• An API key from your chosen provider. For OpenRouter, create the key in the OpenRouter dashboard and confirm the exact model id in its catalog before you save anything in n8n.
• A test workflow idea you can reuse for every model, for example a workflow that reads new rows from a spreadsheet and posts a summary to Slack. Using the same task for each model is what makes a comparison honest.

Step-by-step guide

Step 1: Confirm the Assistant module is not disabled

Before you touch any provider setting, confirm the Assistant module can load at all. Open your environment file and check for this line:

N8N_DISABLED_MODULES=instance-ai

If that line exists, remove instance-ai from it and restart n8n. The official troubleshooting section lists a disabled instance-ai module as the first general cause when the Assistant does not appear. On a one-line install on version 2.35 or later, the module is enabled by default, and the only missing piece is the model key.

Step 2: Choose your route before you edit anything

There are two routes, and choosing the wrong one is the most common source of confusion.

Route A, supported provider, is for Anthropic, OpenAI, or OpenRouter. You set a model value and an API key. You do not set a custom base URL.

Route B, custom OpenAI-compatible endpoint, is for a local server such as LM Studio, or a third-party endpoint that speaks the OpenAI API. You set N8N_INSTANCE_AI_MODEL_URL to that endpoint’s /v1 address, plus an API key if the server requires one.

If you are connecting Moonshot Kimi through a supported gateway, Route A is the safer choice: use OpenRouter as the provider and the gateway’s model id, rather than wiring Moonshot’s direct endpoint into the Assistant and debugging both the endpoint and the model id at the same time. Keep the direct endpoint route for servers you control, where you can read the server log and see the request arrive.

Step 3: Connect a supported provider such as OpenRouter

The fastest way on a one-line install is the editor itself. Open n8n, go to the instance’s AI settings, and add your model key there. Prefer the environment file instead, because it is versioned with the rest of your deployment? Then add these two lines to ./n8n/.env:

N8N_INSTANCE_AI_MODEL=openrouter/moonshotai/kimi-k3
N8N_INSTANCE_AI_MODEL_API_KEY=sk-or-v1-your-openrouter-key-here

The model value follows the documented provider/model format. The official guide gives openrouter/deepseek/deepseek-v4-pro as its OpenRouter example, which shows that the model part can itself contain a slash. Replace the example model id with the exact id from your provider’s catalog, and replace the placeholder key with a real key that you never commit to a repository. Restart n8n after editing the file:

docker compose -f ./n8n/compose.yml up -d

Then open the editor, open the Assistant, and ask it to build your test workflow. If the Assistant answers and starts scaffolding, the provider route works, and any later problem is about model quality or cost, not about connectivity.

Step 4: Connect a direct OpenAI-compatible endpoint

For a local or third-party endpoint, add the endpoint URL to the same environment file. The official guide documents this exact pair:

N8N_INSTANCE_AI_MODEL_URL=http://localhost:1234/v1
N8N_INSTANCE_AI_MODEL_API_KEY=your-endpoint-key-here

Two details in that example deserve attention. First, the URL ends in /v1, because n8n appends the API path to it, so a bare host address without /v1 will fail in a confusing way. Second, the guide notes that some local servers do not require an API key at all, so do not invent a key for a server that accepts anonymous local requests, and do not leave a production endpoint unauthenticated.

If your endpoint runs on a different host than n8n, replace localhost with a hostname the n8n container can actually resolve. localhost inside a container means the container itself, not your laptop and not your host machine. For a server on the same Docker network, use its service name. For a server outside Docker, use its reachable IP or hostname, and check the firewall before you blame the model.

Restart n8n with the same command as in Step 3, then test with the same small workflow task you used for Route A. If the Assistant responds, the endpoint route works. If it does not, read the troubleshooting section before changing a second variable, because changing the URL and the model at the same time destroys the evidence about which one was wrong.

Step 5: Switch models safely, one variable at a time

A model switch should be a controlled change, not a rewrite of your configuration. Follow this order:

1. Save a copy of the working environment file before you edit it, so you can roll back in one command.
2. Change only the model value, or only the endpoint URL, never both in the same restart.
3. Restart n8n and send the same test prompt you used before.
4. Judge the result on three concrete checks: the Assistant builds a workflow that runs, it explains a real error in an existing workflow, and it fixes a small intentional mistake without breaking the rest of the workflow.

A cheaper model that passes all three checks is a better daily default than a flagship model that only passes the first. Keep the flagship for complex builds, and keep the cheaper model for drafting, renaming, and routine fixes. Record which model passed which check in your own runbook, because provider model ids change and a comparison you cannot reproduce is not a comparison.

Step 6: Control cost at the provider, not in n8n

n8n Assistant has no built-in token budget in the settings described here, so cost control lives at the provider. Create a separate API key for the Assistant instance, so its usage is visible separately from workflow node usage. Set a spend cap or alert in the provider dashboard on the day you create the key, not after the first large bill. Review the provider usage page after your first week with a new model, and compare it against the number of Assistant conversations you actually started, not against a feeling that the model seemed expensive.

For a team, use the cheaper model for drafting, reserve the flagship for builds it fails twice, and rotate a key whenever a team member leaves or a key appears in a log or screenshot.

Troubleshooting

The Assistant does not appear after a restart

Check the module first, then the key. Confirm N8N_DISABLED_MODULES does not include instance-ai, confirm the API key is valid for the provider you selected, and confirm the sandbox is enabled. The official troubleshooting list puts these three checks before any provider-specific debugging, and skipping them is how a simple missing key turns into an hour of endpoint debugging. If you use the self-hosted sandbox, run its health check and expect exactly this response:

curl http://sandbox-api:8080/healthz

The expected response is {"status":"ok"}. Replace sandbox-api with your sandbox host if your setup names it differently.

The Assistant still uses the old model after you change the environment file

Check the editor’s AI settings before you edit the file again. A provider choice saved in the user interface can win over a new environment value, so change the provider in the same place where you first set it. Then restart n8n and send a fresh test prompt in a new conversation, because an existing conversation may keep context from the previous model. If the old model still answers, compare the running container’s environment against the file on disk, because editing a .env file for a different Compose project is a quiet and common mistake.

A custom endpoint returns an authentication or connection error

Split the error into three questions. First, can the n8n container reach the endpoint at all? Test the hostname from inside the container’s network, not only from your laptop. Second, does the URL end in /v1? A missing /v1 suffix produces errors that look like authentication failures. Third, is the key valid for that endpoint, not just valid somewhere else? An OpenRouter key does not authenticate a direct Moonshot endpoint, and a local server key does not authenticate a hosted gateway. Fix one question at a time, restart, and retest with the same prompt.

The Assistant answers, but the workflow it builds is worse than before

Do not judge a model on one prompt. Run the same three checks from Step 5. A cheaper model may need more precise prompts, with the trigger, data source, and expected output stated explicitly. If it fails the same build twice with precise prompts, move that class of build back to the stronger model and keep the cheaper model for drafting.

The sandbox starts slowly, or the first Assistant reply takes a long time

Remember the Daytona defaults from the Evidence section: an idle sandbox stops after 15 minutes. A slow first reply after a pause may be a cold sandbox starting, not a slow model. Send a second prompt in the same conversation before concluding the model is slow. For local testing, the bundled sandbox avoids this managed lifecycle, which is one reason to test a new model locally before judging its speed in a production Daytona setup.

FAQ

Does self-hosted n8n Assistant include a model?

No. You bring your own API key, and your provider bills the usage directly. That is why a model switch is a billing decision as well as a quality decision.

What is the safest first custom provider to try?

Start with a supported provider such as OpenRouter, because it needs only a model value and an API key, with no custom base URL to debug. Move to a direct endpoint only after the Assistant works there.

Why does the Assistant still use my old model after I change an environment variable?

Check the editor’s AI settings first, because a saved provider choice there can win over a new environment value. Change it in the same place, restart n8n, and test in a new conversation.

Can I use a local model through an OpenAI-compatible endpoint?

Yes, if the local server exposes an OpenAI-compatible API. Point N8N_INSTANCE_AI_MODEL_URL at its /v1 address, restart n8n, and test with a small workflow task. Some local servers need no key.

Will changing the Assistant model change my existing workflows?

No. It changes only the model that helps you build and fix workflows in the editor. Models inside workflow nodes keep their own credentials and settings.

Conclusion

A custom LLM provider for self-hosted n8n Assistant is a configuration change with a billing consequence, not a new product to install. Start with a supported provider, confirm the sandbox and the module, then move to a direct OpenAI-compatible endpoint only when you control the server and can read its logs. Test every switch with the same workflow task, keep the cheaper model for drafting, and reserve the flagship for builds that earn it. Next, read the n8n Assistant workflow builder guide to put your new model to work on a real build, and the n8n Agent Builder tutorial when you are ready to turn a finished workflow into a durable agent. For the full map of n8n tutorials on this site, start with the complete n8n guide.

Frequently asked questions