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. |
| `N8N_INSTANCE_AI_SANDBOX_LINK_SDK` | boolean | `false` | Local-dev only. When `1` or `true`, pack the workspace `n8n-workflow` and `@n8n/workflow-sdk` tarballs from the host monorepo into each sandbox after `npm install`, overriding the registry copies. Use when master is ahead of npm (e.g. unreleased exports such as `normalizeNodeShape`). Requires `pnpm build` in `packages/workflow` and `packages/@n8n/workflow-sdk`. Start a new AI thread after changing this — existing sandboxes keep their initialized `node_modules`. |

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`:

```bash
N8N_DISABLED_MODULES=instance-ai
```

## MCP Server Configuration

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

```bash
# 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
`true` since Gate A of the durable-log rollout; pre-existing runs are
backfilled by migration). 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`). Setting it to `false` is the rollback
switch until the legacy paths sunset at Gate B: events then 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).

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

```bash
# 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:

```yaml
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`:

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

Most SearXNG Docker images enable JSON format by default.