n8n/packages/@n8n/instance-ai/docs/configuration.md

Configuration

Environment Variables

All Instance AI configuration is done via environment variables.

Core

Variable	Type	Default	Description
N8N_INSTANCE_AI_MODEL	string	anthropic/claude-opus-4-8	LLM model in provider/model format for built-in providers, or a bare model name when N8N_INSTANCE_AI_MODEL_URL is set. Must be set for the module to enable.
N8N_INSTANCE_AI_MODEL_URL	string	''	Base URL for an OpenAI-compatible endpoint (e.g. http://localhost:1234/v1 for LM Studio). When set, model requests go to this URL instead of the built-in provider.
N8N_INSTANCE_AI_MODEL_API_KEY	string	''	API key for the custom model endpoint. Optional — some local servers don't require one.
N8N_INSTANCE_AI_MCP_SERVERS	string	''	Comma-separated MCP server configs. Format: name=url,name=url
N8N_INSTANCE_AI_LOCAL_GATEWAY_DISABLED	boolean	false	Disable the local gateway (filesystem, shell, browser) for all users

Tracing

Variable	Type	Default	Description
N8N_DIAGNOSTICS_ENABLED	boolean	true	When set to false, Instance AI tracing is disabled.
LANGSMITH_API_KEY / LANGCHAIN_API_KEY	string	unset	Enables direct LangSmith export for local and self-hosted setups.
LANGSMITH_ENDPOINT / LANGCHAIN_ENDPOINT	string	unset	Optional direct LangSmith endpoint override.
LANGSMITH_TRACING / LANGCHAIN_TRACING_V2	boolean	unset	LangSmith SDK tracing flags. false disables tracing; true enables direct tracing when direct LangSmith credentials or endpoints are configured.

Debugging

Variable	Type	Default	Description
N8N_INSTANCE_AI_RUN_DEBUG_ENABLED	boolean	false	Capture orchestrator LLM steps and workflow code snapshots for the dev debug panel and eval LLM debug reports.
N8N_INSTANCE_AI_EVAL_TIMING	boolean	false	When true, logs a per-execution [EvalMock][timing] phase breakdown (hints / bypass-pin / http-mock / ai-turn) for the eval mock-execution path, to attribute mocked-execution latency. A no-op otherwise.

Memory

Variable	Type	Default	Description
N8N_INSTANCE_AI_LAST_MESSAGES	number	20	Number of recent messages to include in context

Filesystem

Variable	Type	Default	Description
N8N_INSTANCE_AI_GATEWAY_API_KEY	string	''	Static API key for the filesystem gateway. Used by the @n8n/computer-use daemon to authenticate SSE and HTTP POST requests. When empty, the dynamic pairing token flow is used instead.

Filesystem access requires the @n8n/computer-use gateway daemon. The user runs npx @n8n/computer-use https://<your-n8n-instance> on their machine to connect.

See docs/filesystem-access.md for the full architecture, gateway protocol spec, and security model.

Web Research

Variable	Type	Default	Description
INSTANCE_AI_BRAVE_SEARCH_API_KEY	string	''	Brave Search API key. Takes priority over SearXNG when set.
N8N_INSTANCE_AI_SEARXNG_URL	string	''	SearXNG instance URL (e.g. http://searxng:8080). Empty = disabled. No API key needed.

Provider priority: Brave (if key set) > SearXNG (if URL set) > disabled. When no search provider is available, the web-search action is disabled. fetch-url still works.

Sandbox (Code Execution)

Variable	Type	Default	Description
N8N_INSTANCE_AI_SANDBOX_ENABLED	boolean	false	Enable sandbox-backed workflow building. When false, workflow builder capability is unavailable.
N8N_INSTANCE_AI_SANDBOX_PROVIDER	string	n8n-sandbox	Sandbox provider: n8n-sandbox for the n8n sandbox service, or daytona for the Daytona provider.
DAYTONA_API_URL	string	''	Daytona API URL (e.g. https://app.daytona.io/api). Required when provider is daytona.
DAYTONA_API_KEY	string	''	Daytona API key for authentication. Required when provider is daytona.
N8N_SANDBOX_SERVICE_URL	string	''	n8n sandbox service URL. Required when provider is n8n-sandbox.
N8N_SANDBOX_SERVICE_API_KEY	string	''	API key for the n8n sandbox service. Optional when an httpHeaderAuth credential is selected in admin settings.
N8N_INSTANCE_AI_SANDBOX_IMAGE	string	daytonaio/sandbox:0.5.0	Docker image for the Daytona sandbox.
N8N_INSTANCE_AI_SANDBOX_SNAPSHOT	string	''	Overrides the full Daytona snapshot name (e.g. n8n/instance-ai:2.27.3) used to create sandboxes. Defaults to the versioned snapshot derived from the running n8n version. Only applies in proxy mode; the snapshot must exist or Daytona falls back to building from the base image.
N8N_INSTANCE_AI_SANDBOX_TIMEOUT	number	300000	Default command timeout in the sandbox (milliseconds).
N8N_INSTANCE_AI_SANDBOX_NAME_PREFIX	string	''	Prefix prepended to every Daytona sandbox name (e.g. eval-baseline-daily). Also surfaced as a name_prefix label. Empty in production.
N8N_INSTANCE_AI_SANDBOX_EPHEMERAL	boolean	false	When true, Daytona sandboxes are created ephemeral (auto-deleted on stop) instead of lingering stopped. Intended for throwaway eval instances so sandboxes don't accumulate.
N8N_INSTANCE_AI_SANDBOX_AUTO_STOP_MINUTES	number	15	Minutes an idle Daytona sandbox waits before being stopped. 0 disables auto-stop.
N8N_INSTANCE_AI_SANDBOX_AUTO_ARCHIVE_MINUTES	number	60 (1 hour)	Minutes a stopped Daytona sandbox waits before being archived to cold storage. 0 uses Daytona's maximum interval.
N8N_INSTANCE_AI_SANDBOX_AUTO_DELETE_MINUTES	number	10080 (7 days)	Minutes a stopped Daytona sandbox waits before being deleted. Negative disables auto-delete; 0 deletes on stop. Ignored when N8N_INSTANCE_AI_SANDBOX_EPHEMERAL is true.

When sandbox is enabled, Instance AI writes workflow source files in the runtime workspace and build-workflow runs TypeScript sources through the sandbox tsx build runner before saving. The model still calls only build-workflow; there is no no-sandbox TypeScript build fallback.

Sandbox workspaces persist per thread — the same container is reused across messages in a conversation. Workspaces are destroyed on server shutdown.

Observational Memory

Variable	Type	Default	Description
N8N_INSTANCE_AI_OBSERVER_MESSAGE_TOKENS	number	30000	Token threshold for Observer to trigger compression
N8N_INSTANCE_AI_REFLECTOR_OBSERVATION_TOKENS	number	40000	Token threshold for Reflector to condense observations

Observer and Reflector use the same model as the orchestrator agent (see @n8n/agents observational memory defaults).

Lifecycle & Housekeeping

Variable	Type	Default	Description
N8N_INSTANCE_AI_THREAD_TTL_DAYS	number	30	Conversation thread TTL in days. Threads older than this are auto-expired. 0 = no expiration.
N8N_INSTANCE_AI_PRUNE_INTERVAL	number	3600000	Interval in ms between scheduled pruning runs on the leader. Prunes stale checkpoints, expired pending confirmations, and expired conversation threads. 0 = disabled.
N8N_INSTANCE_AI_SNAPSHOT_RETENTION	number	86400000	Retention period in ms for orphaned workflow snapshots before pruning.
N8N_INSTANCE_AI_CONFIRMATION_TIMEOUT	number	86400000	Timeout in ms for HITL confirmation requests. 0 = no timeout.

Output Filtering

Agent output is scanned for secrets/PII and redacted before it reaches the user. The scan covers streamed assistant text, reasoning, and tool results/errors, for both the orchestrator and eval-setup background tasks. A filtering event (categories and counts only — never the values) is logged whenever a redaction occurs.

Variable	Type	Default	Description
N8N_INSTANCE_AI_OUTPUT_REDACTION_ENABLED	boolean	true	Master switch. When false, output passes through untouched.
N8N_INSTANCE_AI_OUTPUT_REDACTION_SECRETS	boolean	true	Redact credential/secret patterns (API keys, tokens, auth headers, key=value pairs).
N8N_INSTANCE_AI_OUTPUT_REDACTION_PII	string	credit-card	Comma-separated PII categories to redact. Available: email, credit-card (Luhn-validated), ssn-us (US Social Security Number, dashed 123-45-6789 form). Defaults to credit-card only; email/ssn-us are implemented but off by default pending review of false-positive rates. Empty = no PII scanning. Unrecognized values are ignored. Per-country national IDs each use their own ssn-<cc> category (e.g. a future ssn-uk).
N8N_INSTANCE_AI_OUTPUT_REDACTION_PLACEHOLDER	string	[REDACTED]	Replacement text substituted for each redacted match.

Secret detection is conservative by design — it matches well-known token shapes and explicit key=value/JSON secret fields, not arbitrary opaque strings, to avoid mangling normal output. The PiiDetectionType API also reserves phone and address, but those have no detection pattern yet — setting them has no effect (they were deferred as too false-positive-prone for free-form prose).

Enabling / Disabling

The module is enabled when N8N_INSTANCE_AI_MODEL is set to a non-empty value.

The module can be disabled explicitly by adding it to N8N_DISABLED_MODULES:

N8N_DISABLED_MODULES=instance-ai

MCP Server Configuration

MCP servers are configured as comma-separated name=url pairs:

# Single server
N8N_INSTANCE_AI_MCP_SERVERS="github=https://mcp.github.com/sse"

# Multiple servers
N8N_INSTANCE_AI_MCP_SERVERS="github=https://mcp.github.com/sse,database=https://mcp-db.example.com/sse"

Each MCP server's tools are merged with the native tools and made available to the orchestrator agent. Sub-agents currently do not receive MCP tools.

Storage

Instance AI memory persists in the main n8n database via TypeORM — the same PostgreSQL or SQLite instance n8n already uses. No separate memory database or LibSQL file is required.

The same storage backend is used for:

• Message history
• Observational memory (observation log, cursors, and task locks)
• Plan storage (thread-scoped in thread metadata)
• Run snapshots and checkpoints (separate tables)

Event Bus

The event bus transport is selected automatically:

• Single instance: In-process EventEmitter — zero infrastructure
• Queue mode: Redis Pub/Sub — uses n8n's existing Redis connection

Event persistence is controlled by N8N_INSTANCE_AI_DURABLE_LOG (default false). Off, events live only in a bounded in-memory buffer per thread (500 events / 2 MB, FIFO-evicted; ids reset on restart, so replay does not survive a restart). On, coalesced step-level facts (completed text/reasoning blocks, tool calls and results, run lifecycle) are appended to the instance_ai_events table and replay reads the database; token deltas are never persisted. Rows cascade-delete with their thread (N8N_INSTANCE_AI_THREAD_TTL_DAYS).

Runtime behavior:

• One active run per thread. Additional POST /instance-ai/chat/:threadId requests while a run is active are rejected (409 Conflict).
• Runs can be cancelled via POST /instance-ai/chat/:threadId/cancel (idempotent).

Minimal Setup

# Minimal — just set the model
N8N_INSTANCE_AI_MODEL=anthropic/claude-opus-4-8

# With MCP servers
N8N_INSTANCE_AI_MCP_SERVERS="my-tools=https://mcp.example.com/sse"

# With SearXNG (free, self-hosted search)
N8N_INSTANCE_AI_SEARXNG_URL=http://searxng:8080

# With Brave Search (paid API, takes priority over SearXNG)
INSTANCE_AI_BRAVE_SEARCH_API_KEY=BSA-xxx

# With sandbox (n8n sandbox service)
# CI can start it with:
# pnpm tsx packages/testing/containers/start-sandbox.ts --network n8n-eval-net
N8N_INSTANCE_AI_SANDBOX_ENABLED=true
N8N_INSTANCE_AI_SANDBOX_PROVIDER=n8n-sandbox
N8N_SANDBOX_SERVICE_URL=https://sandbox.example.com
N8N_SANDBOX_SERVICE_API_KEY=sandbox-key

# With sandbox (Daytona — explicit provider)
N8N_INSTANCE_AI_SANDBOX_ENABLED=true
N8N_INSTANCE_AI_SANDBOX_PROVIDER=daytona
DAYTONA_API_URL=https://app.daytona.io/api
DAYTONA_API_KEY=dtn_xxx

# With filesystem gateway (user runs daemon on their machine)
N8N_INSTANCE_AI_GATEWAY_API_KEY=my-secret-key
# User runs: npx @n8n/computer-use

# With custom OpenAI-compatible endpoint (e.g. LM Studio, Ollama)
N8N_INSTANCE_AI_MODEL=your-tool-capable-model
N8N_INSTANCE_AI_MODEL_URL=http://localhost:1234/v1

# Output filtering — secrets + email only, with a custom placeholder
N8N_INSTANCE_AI_OUTPUT_REDACTION_PII=email
N8N_INSTANCE_AI_OUTPUT_REDACTION_PLACEHOLDER=‹redacted›

# Observational memory tuning
N8N_INSTANCE_AI_OBSERVER_MESSAGE_TOKENS=30000

SearXNG Setup (Docker Compose)

SearXNG is a self-hosted metasearch engine that aggregates results from Google, Bing, DuckDuckGo, and others. No API key needed.

Add N8N_INSTANCE_AI_SEARXNG_URL pointing to your SearXNG service:

services:
  searxng:
    image: searxng/searxng:latest
    ports:
      - "8888:8080"  # optional: expose to host
  n8n:
    environment:
      N8N_INSTANCE_AI_MODEL: anthropic/claude-opus-4-8
      N8N_INSTANCE_AI_SEARXNG_URL: http://searxng:8080

SearXNG must have JSON format enabled in its settings.yml:

search:
  formats:
    - html
    - json   # required for Instance AI

Most SearXNG Docker images enable JSON format by default.