Canonical guide · Source docs/ai-assistant.md

n8n AI Assistant companion

Relmio can install n8n's self-hosted AI Assistant sandbox and optional SearXNG web search through local Docker discovery or an SSH host. Neither route reads a ChatGPT/Codex sign-in or uses the OAuth sidecar.

Preview: AI Assistant is Preview. Review every generated workflow before activating it, and use n8n's recommended Daytona sandbox for production.

What the wizard changes

For n8n on the same computer, start the standard local wizard and choose n8n AI Assistant tools. Direct local Docker-socket discovery works on native Windows with Docker Desktop's desktop-linux engine, macOS, Linux, and Linux under WSL2. Relmio records the selected n8n container, network, and SearXNG choice, then creates only ~/.relmio/local/n8n-ai-assistant after you confirm.

For an SSH-reachable host, run relmio assistant. Use an already-approved direct-root account with Local SSH agent or password authentication. The separate Passwordless sudo -n (model only) session cannot install or manage the Assistant, whose configuration contains generated secrets; do not enable root/password SSH to work around that limit. After SSH host-key confirmation, read-only n8n discovery, a selected existing Docker network, and final confirmation exactly set to true, Relmio may first create /docker/n8n-openai-oauth and write its shared mode-0600 Relmio root marker. The root-owned, non-symlink /docker parent must already exist without group/other write permission. Relmio then creates only the assistant-sandbox child there. The SSH path does not write existing n8n project files. Both paths use an independent Compose project identity recorded in a strict, mode-0600 Assistant marker and keep n8n configuration operator-owned.

The required companion has three services:

• relmio-sandbox-certs bootstraps mTLS certificates once.
• relmio-sandbox-api provides the n8n Sandbox Service API.
• relmio-sandbox-runner-1 is a privileged Docker-in-Docker runner on its own unpublished Compose network. Treat it as equivalent to root on the host. It needs egress to pull n8n's sandbox image on first use.
• relmio-searxng provides optional JSON web search only when you opt in during the reviewed plan. Web search is off by default; Relmio never adds it silently.

Compose assigns the companion's containers short deterministic names derived from the first 16 hexadecimal characters of its recorded installation ID, such as relmio-ai-<generated-id>-api. The full 128-bit ID remains in ownership labels and the managed marker. Existing markers remain valid without migration; a later separately confirmed companion update may recreate only its own containers to adopt these names. It never renames, recreates, restarts, stops, or executes inside n8n.

The sandbox API joins the selected existing n8n Docker network. When enabled, SearXNG joins it with a separately generated collision-resistant, Docker-internal alias. The selection and aliases are stored in the strict, versioned managed assistant marker and reused for updates. The result view always shows the sandbox URL and shows this additional stable URL only when web search is enabled:

http://relmio-ai-sandbox-<generated-id>:8080
http://relmio-ai-searxng-<generated-id>:8080  (when enabled)

There are no ports: mappings, reverse-proxy routes, or changes to the existing n8n Compose file, image, container, or workflows. Relmio never stops, restarts, recreates, rebuilds, or executes inside n8n.

Prerequisites Relmio will not change

The SSH-host workflow read-only inspects the selected n8n container and returns only an allowlisted prerequisite status: whether its N8N_ENABLED_MODULES setting is missing, configured without instance-ai, or enabled with instance-ai. It never returns the container environment or the raw setting value. The wizard refuses installation unless instance-ai is enabled.

Apply the prerequisite through the existing n8n deployment workflow. When the variable is missing, use this exact form in the existing n8n service:

N8N_ENABLED_MODULES=instance-ai

When the variable already contains module entries but lacks instance-ai, append instance-ai as a distinct comma-delimited token while preserving existing module entries. Do not replace unknown existing values. For example:

# Existing service configuration
N8N_ENABLED_MODULES=module-a,module-b

# Preserve existing entries and append the required token
N8N_ENABLED_MODULES=module-a,module-b,instance-ai

Use your existing n8n deployment workflow; Relmio does not claim a provider-specific UI path. Apply the change to the existing n8n service, then redeploy or restart n8n, verify that n8n is healthy, reconnect to Relmio, and run discovery again before reviewing a new plan.

After either wizard verifies the companion stack, it returns an exact companion-settings block containing only the sandbox enabled flag, provider, immutable sandbox image, private sandbox URL, a sandbox API key when a new key was returned, and the optional private SearXNG URL. The apply block deliberately excludes N8N_ENABLED_MODULES: preserve its existing value and ensure it continues to include instance-ai. Apply only the returned companion settings through your own n8n deployment workflow. Relmio will not edit the existing n8n Compose file, image, or environment; restart or recreate n8n; or exec into n8n to make this prerequisite change. It reports only the allowlisted status, never the raw environment value. Plan for at least 4 GB RAM and 2 vCPU for the n8n and companion workload; capacity needs can be higher for real workflows.

Enter the result values in n8n

Relmio generates four separate local 256-bit secrets: the sandbox API key, runner registration token, runner API key, and SearXNG secret. It uploads the secrets only in the managed mode-0600 .env file on the SSH path and writes them only to that same owned file on the direct local path. The registration, runner, and SearXNG secrets are never returned or logged. A newly generated sandbox API key is shown once in the result view. When a managed SSH update intentionally keeps the existing sandbox credentials, the result returns no sandbox key, omits N8N_SANDBOX_SERVICE_API_KEY from the companion-settings block, and tells the operator to retain the original key. Even with web search disabled, the private SearXNG secret remains in that .env: this lets a later reviewed opt-in start only the new SearXNG service without overwriting the running sandbox/runner credentials. No SearXNG service, settings file, alias probe, URL, or host port is created while it is disabled.

In n8n's AI Assistant settings, enter:

URLs are stable generated result values; only the sandbox API key is one-time-displayed. SearXNG has no user-facing key. When enabled, its generated settings explicitly enable the JSON response format n8n needs.

The includeSearxng choice is an exact boolean in the reviewed plan and final confirmation request; missing, string, or otherwise ambiguous values are rejected. A managed disabled installation can later enable SearXNG only after Relmio re-attests the existing sandbox resources and the missing SearXNG resource name, then starts only SearXNG. Disabling an already managed SearXNG service would stop or remove it, so Relmio rejects that change and requires a separately authorized cleanup path instead.

Immutable companion image pins

Every generated production image reference is the reviewed full tag@sha256:<OCI-index-digest> value. The API/certificate service, privileged runner, and nested sandbox are reviewed as one compatible n8n Sandbox Service unit; optional SearXNG is pinned independently. Generated Compose never uses latest, stable, a tag-only reference, a digest-only reference, environment interpolation, or user input for these images.

The upstream review sources are the n8n Sandbox Service repository, its API, runner, and nested sandbox GHCR package pages; and the SearXNG repository and GHCR package page. The n8n setup documentation remains authoritative for product configuration.

For a managed companion, an image change is never automatic: update Relmio locally, reconnect for host-key confirmation and read-only discovery, review the exact companion-only plan, preserve the recorded SearXNG choice unless you deliberately change it, and provide final confirmation. Then verify that only managed companion resources changed, no host ports were published, and n8n is healthy. Roll back only with the full previously reviewed immutable pin set through that same separately confirmed managed update; never pull a moving tag or mutate n8n directly. The maintainer procedure is in maintenance.md.

Operator-managed Daytona handoff

The authenticated hosting planner offers a separate n8n-native Daytona configuration handoff for 15 self-hosted platform targets. It is not the managed privileged runner described above and does not install a sandbox, provision a Daytona account, or apply/restart existing n8n. The operator preserves all existing N8N_ENABLED_MODULES entries and includes instance-ai, then applies the listed settings through their normal n8n maintenance process:

N8N_INSTANCE_AI_SANDBOX_ENABLED=true
N8N_INSTANCE_AI_SANDBOX_PROVIDER=daytona
N8N_INSTANCE_AI_SANDBOX_IMAGE=daytonaio/sandbox:0.5.3-slim
DAYTONA_API_URL=https://app.daytona.io/api

Put the actual DAYTONA_API_KEY into the existing n8n secret store at runtime; the planner neither requests nor emits its value. Configure N8N_INSTANCE_AI_MODEL and any required N8N_INSTANCE_AI_MODEL_API_KEY independently. An optional search provider is likewise configured separately through a reachable N8N_INSTANCE_AI_SEARXNG_URL or an operator-owned Brave credential. Verify that a harmless workflow really performs a Daytona sandbox operation; account access, capacity, model choice, search reachability and runtime behavior are not validated by generating the handoff.

The 15 profiles cover Render, Railway, Fly.io, DigitalOcean App Platform, ECS EC2/Fargate, EKS EC2/Fargate, GKE Standard/Autopilot, AKS, Cloud Run, Azure Container Apps, Azure Container Instances and Lightsail Containers. They replace only the sandbox provider; they do not provide an OpenAI bridge, model, SearXNG service, or Relmio-managed Assistant runner. n8n documents Daytona as its production sandbox alternative in Set up AI Assistant.

Model routes

Direct OpenAI provider

Choose OpenAI in n8n and keep the current supported model selection. If your n8n instance continues to accept this selection, preserve it:

openai/gpt-5.6-sol

Enter your own OpenAI Platform API key directly in n8n. Relmio does not request, read, transmit, retain, or configure this model credential.

An example model shown in n8n documentation is not a migration requirement. Change models only if n8n rejects the current selection or you deliberately choose another supported model.

ChatGPT/Codex subscription sign-in is not an OpenAI Platform API key, so it does not work with the OpenAI provider. To try the ChatGPT plan sidecar instead, see Optional: ChatGPT plan sidecar.

A Relmio-managed local model for an n8n workflow is a separate Chat Model endpoint. Installing it does not install or enable n8n's Assistant sandbox, and its unauthenticated model API is not an AI Assistant credential. The model's tool-call behavior must be tested separately; local-model capacity does not replace the Assistant's sandbox requirements or production guidance.

Optional: custom OpenAI-compatible endpoint

n8n's custom/self-hosted OpenAI-compatible dialog defaults to an Ollama-style route with Base URL, API key, and Model ID fields. Use it only if you already run a separate, n8n-reachable Relmio OpenAI-compatible endpoint backed by a user-owned OpenAI Platform API key.

• Base URL: that endpoint's /v1 address.
• API key: that endpoint's private Relmio client credential. It is not an OpenAI-issued API key.
• Model ID: a model ID exposed by the Platform-key-backed endpoint.

Optional: ChatGPT plan sidecar

The Assistant wizard does not create or select the ChatGPT plan sidecar. You can point the Assistant at an installed sidecar yourself:

1. Get a model ID. On a VPS, choose Check installed account in Manage the installed ChatGPT session, then use Copy ID in the Models panel on a model marked In n8n. On a local sidecar, copy an ID from the OpenAI Chat Model node's list.
2. In n8n, open Settings > n8n Assistant. Under Model, choose Self-hosted or OpenAI-compatible endpoint. These labels are from n8n 2.40.7.
3. Enter the Base URL http://n8n-openai-oauth:10531/v1, the same Relmio key as your n8n OpenAI credential, and paste the model ID into Model.

The Assistant never reads the sidecar's model list. For this endpoint type n8n shows a free-text Model field, so new models do not appear there. The Assistant also keeps its own copy of the key, so when Relmio issues a new key, update it here as well as in the OpenAI credential.

n8n turns the Assistant on for everyone on the instance. Only do this if nobody else uses this n8n: their Assistant chats would use your ChatGPT plan.

How the sidecar handles the Assistant's requests:

• n8n's model check asks for at most 16 output tokens. Sign in with ChatGPT doesn't accept an output-token cap, so the sidecar drops it and the 16-token cap is not enforced.
• In tool steps and follow-up messages, the Assistant refers to its earlier reasoning and replies by ID instead of sending them again. The sidecar keeps them in memory from completed responses and puts them back into the request. The memory is never written to disk, holds at most 4,096 items or 32 MiB, and keeps each item for up to 6 hours. A sidecar restart or update empties it. The model then no longer sees its earlier reasoning and replies in an open conversation, so start a new one. Earlier tool calls and results are sent in full and are not affected.
• When a streamed response fails or is cut off, the sidecar sends the error in OpenAI's format, so the Assistant gets the real error instead of a validation error or an empty answer.
• One request can list up to 128 tools, including tools from MCP servers. A request with more is refused.

If the model check fails with This Responses parameter is unavailable with ChatGPT plan usage., the sidecar was built by an older Relmio version. On a VPS, update it with Review sidecar update; see Update the installed sidecar. Request details are in AI Assistant requests.

On 2026-10-07 the sidecar on the owner's VPS was updated with this change. n8n 2.40.7's Assistant then used it on one ChatGPT account (Pro plan) with the model gpt-6-astra, set up as in the steps above. n8n's model check passed and the setting saved. "Reply with OK" returned "OK", and "Which workflows do I have?" ran a tool step and listed the instance's workflows, published and unpublished, in about 35 seconds. Before the update, the same setup failed. The key saved in the Assistant was out of date and got 401 A local client credential is required., and with the current key the model check failed with This Responses parameter is unavailable with ChatGPT plan usage. This one test is no guarantee for other accounts, models or longer conversations, or after a sidecar restart, which drops earlier context. The sidecar adds no logs, so the test also doesn't show whether earlier items were filled in from memory.

The sidecar still refuses other request fields and tools it cannot keep, so some Assistant features may fail. OpenAI hasn't said whether this use fits its Sign in with ChatGPT terms; SIWC Terms §2 limits use to the connected application. See the 2026-10-06 source check and the 2026-10-07 Assistant check.

n8n stores Assistant conversations and outputs in its own database, and sends traces to LangSmith if you set that up. The sidecar keeps earlier reasoning and replies only in memory, as described above, and adds no logs; see Remembered Responses items. Assistant model use counts toward your plan's limits.

Platform account guardrails

No setup can guarantee an account is never flagged. For the direct OpenAI provider route, use a dedicated OpenAI Platform project/key, keep the key in n8n's server-side credential storage, and set project rate/spend limits and alerts. Enable usage monitoring, grant least user access, plan rotation/revocation, require human review for generated workflows, and keep the provider path free of public exposure.

Relmio cannot inject per-user safety identifiers or moderation into n8n's direct provider path. Configure any controls available in your Platform project and n8n instance; this companion cannot make claims about provider enforcement.

Verification and failure behavior

Before start, the companion Compose configuration is validated. After start, Relmio verifies sandbox API health, the expected running services for the selected web-search option, and the absence of every host-published port. Immediately before any companion write, it reruns the selected container's read-only network and prerequisite discovery. The selected network must still exist and the allowlisted instance-ai status must still be enabled and match the reviewed plan; a changed result consumes that plan without installing.

For a new companion or a normal managed update, a post-start safety failure stops and removes only the companion project. When adding SearXNG to an existing managed sandbox, post-start cleanup removes only the optional SearXNG service: the existing sandbox remains and must not be used until an administrator verifies its state. If cleanup cannot be confirmed, treat the installation as unsafe and do not use the companion until an administrator verifies the relevant managed state.

The bounded command allowlist refuses an unmanaged assistant directory, symlinked assistant paths, and a symlinked or non-directory /docker/n8n-openai-oauth parent. It accepts Docker names only after validation. Before any update, start, or cleanup, Relmio attests that matching project containers, networks, and volumes carry the recorded install identity; it never cleans up an unattested project. It also checks every predictable generated companion container name, the explicit internal network, and the TLS volume regardless of Compose project labels: a new install refuses any match, while an update requires the recorded identity labels on every match.

Reference

• n8n: Set up AI Assistant
• n8n: Docker Compose installation