n8n/packages/@n8n/fs-proxy/spec/local-gateway.md

Local Gateway — Feature Specification

Backend technical design: technical-spec.md

Overview

The Local Gateway is a feature of n8n's Instance AI that allows a user to connect their local machine to the n8n instance. Once connected, the n8n AI Agent gains access to capabilities on the user's machine — such as reading local files, executing shell commands, controlling the screen, and automating a browser.

This enables the AI to assist with tasks that require local context: reading source code, running scripts, interacting with desktop applications, or browsing the web on behalf of the user.

---

Capabilities

The Local Gateway exposes four capability groups. Which capabilities are available depends on what the local machine supports. The user can enable or disable each capability individually before connecting.

1. Filesystem Access

The AI can read files and navigate the directory structure within a user-specified root directory. Access is strictly scoped — the AI cannot access files outside the configured root.

Read operations (always available when filesystem is enabled)

• Read file — read the text content of a file. Files larger than 512 KB or binary files are rejected. Supports paginated access via a start line and line count (default: 200 lines).
• List files — list the immediate children of a directory. Results can be filtered by type (file, directory, or all) and capped at a maximum count (default: 200).
• Get file tree — get an indented directory tree starting from a given path. Traversal depth is configurable (default: 2 levels). Common generated directories (node_modules, dist, .git, etc.) are excluded automatically.
• Search files — search for a regex pattern across all files under a directory. Supports an optional glob filter (e.g. **/*.ts), case-insensitive mode, and a result cap (default: 50 matches). Files larger than 512 KB are skipped.

Write operations (requires writeAccess to be enabled)

Write operations are disabled by default. They must be explicitly enabled via the writeAccess configuration property on the filesystem capability. This gives the user clear, deliberate control over whether the AI is permitted to modify the local filesystem.

When writeAccess is enabled, the following additional operations become available:

• Write file — create a new file with the given content. Overwrites if the file already exists. Parent directories are created automatically. Content must not exceed the maximum file size*.
• Edit file — apply a targeted search-and-replace to an existing file. Finds the first occurrence of an exact string and replaces it with the provided replacement. Fails if the string is not found. File must not exceed the maximum file size*.
• Create directory — create a new directory. Idempotent: does nothing if the directory already exists. Parent directories are created automatically.
• Delete — delete a file or directory. Deleting a directory removes it and all of its contents recursively.
• Move — move or rename a file or directory to a new path. Overwrites the destination if it already exists. Parent directories at the destination are created automatically.
• Copy file — copy a file to a new path. Overwrites the destination if it already exists. Parent directories at the destination are created automatically.

All write operations are subject to the same path-scoping rules as read operations — paths outside the configured root are rejected.

* Maximum file size: 512 KB.

Configuration

The filesystem capability is configured with two properties:

dir         — the root directory the AI can access (required)
writeAccess — enables write operations (default: false)

Exposed as CLI flags --filesystem-dir <path> and --filesystem-write-access, and as env vars N8N_GATEWAY_FILESYSTEM_DIR and N8N_GATEWAY_FILESYSTEM_WRITE_ACCESS.

2. Shell Execution

The AI can execute shell commands on the local machine. This allows it to run scripts, build tools, CLI utilities, or any other command available in the user's shell environment.

3. Computer Control

The AI can observe and interact with the user's screen:

• Screenshot — capture the current screen state
• Mouse control — move the cursor, click, double-click, drag, scroll
• Keyboard control — type text, press keys, trigger keyboard shortcuts

This allows the AI to interact with desktop applications that have no API.

4. Browser Automation

The AI can control a web browser: navigate to URLs, click elements, fill forms, read page content, manage cookies and storage, and execute JavaScript. Three session modes are supported:

• Ephemeral — a clean, temporary browser context with no persistent data
• Persistent — a named browser profile that retains cookies and history across sessions
• Local — the user's real installed browser, using their actual profile and data

---

Connection Flow

1. Capability Preview & Configuration

Before the Local Gateway initiates a connection to the n8n instance, the user is shown a list of capabilities that the local machine supports. Capabilities that are not available on the machine (e.g. computer control on a headless server) are indicated as unavailable.

The user can enable or disable each capability individually. This gives the user explicit control over what the AI is permitted to do on their machine for this connection.

The user must confirm the capability selection before the connection proceeds.

2. Establishing a Connection

After the user confirms, the Local Gateway connects to the n8n instance and registers the selected capabilities. The AI Agent is immediately aware of which tools are available and can use them in subsequent conversations.

3. Active Connection

While connected:

• The user can see that their Local Gateway is active.
• The AI can invoke any of the registered capabilities as needed during a conversation.
• The connection persists across page reloads.

4. Disconnection

The user can explicitly disconnect the Local Gateway at any time. After disconnection, the AI no longer has access to any local capabilities. If the Local Gateway process on the user's machine stops unexpectedly, the connection is terminated and the AI loses access.

---

Access Control & Isolation

Per-User Connections

Each Local Gateway connection is tied to a single user. A user's connection is private — other users on the same n8n instance cannot see it, access it, or use it. Only one active connection is allowed per user at a time.

Filesystem Scope

When connecting, the user specifies a root directory. The AI can only access files within that directory and its subdirectories. Access to any path outside the root is denied — this applies equally to read and write operations.

Write access is an opt-in: even within the root, the AI cannot modify the filesystem unless writeAccess is explicitly enabled. Read and write access are independent — read-only mode remains the default.

---

Permission Management

The Local Gateway uses a two-tier permission model: tool group permission modes (coarse-grained, configured at startup) and resource-level rules (fine-grained, confirmed at runtime during tool execution).

Tool Group Permission Modes

Each tool group has an independent permission mode, configured before the gateway connects and stored in the gateway configuration file.

Tool Group	Available Modes
Filesystem Access	Deny / Ask / Allow
Filesystem Write Access	Deny / Ask / Allow
Shell Execution	Deny / Ask / Allow
Computer Control	Deny / Ask / Allow
Browser Automation	Deny / Ask / Allow

Deny — The tool group is disabled. Its tools are not registered with the n8n instance; the AI has no knowledge of them.

Ask — The tool group is enabled. Before each tool execution the user is prompted to confirm. Confirmation is scoped to a resource (see below). Existing resource-level rules are applied automatically without prompting.

Allow — The tool group is enabled. All tool calls execute without user confirmation. Resource-level always allow rules have no effect in this mode. Permanently stored always deny rules still take precedence and will block the matching resources.

Constraints:

• The gateway cannot start unless at least one tool group is set to Ask or Allow.
• If Filesystem Access is set to Deny, Filesystem Write Access is also disabled regardless of its own mode.

---

Resource-Level Rules

When a tool group operates in Ask mode, confirmation is scoped to a resource. The resource is defined by the tool itself. For Browser Automation the resource is the domain (e.g. github.com). For Shell Execution the resource is the normalized command: wrapper commands (sudo, env, etc.) and environment variable assignments are stripped, and the executable basename replaces an absolute path (e.g. sudo apt install foo → apt install foo). Compound or otherwise unrecognizable commands (chained operators, command substitution, variable-indirect execution, relative paths) are returned as-is so the full command is visible in the confirmation prompt. For other tool groups the resource is determined by the respective tool.

Resource-level always deny rules take precedence over the tool group permission mode. A resource with a stored always deny rule is blocked regardless of whether the tool group is set to Ask or Allow. All other resource-level rules (allow once, allow for session, always allow) apply only when the tool group is in Ask mode.

Rule Types

Rule	Effect	Persistence
Allow once	Execute this specific invocation only	Not stored
Allow for session	Execute all invocations of this resource until the session ends	In-memory, cleared on session end
Always allow	Execute all future invocations of this resource	Stored permanently in config
Deny once	Block this specific invocation only	Not stored
Always deny	Block all future invocations of this resource	Stored permanently in config

Permanently stored resource-level rules (always allow, always deny) are stored in the gateway configuration file, separately from the tool group permission modes.

---

Runtime Confirmation Prompt

When a tool group is in Ask mode and no stored rule applies to the resource, the user is presented with a confirmation prompt. The prompt shows:

• The tool group being used
• The resource being accessed (domain, command, path, etc.)
• A description of the action the AI intends to perform
• The confirmation options: Allow once, Allow for session, Always allow, Deny once, Always deny

---

Session

A session is defined as a single active connection between the Local Gateway and the n8n instance. A session ends when the user explicitly disconnects or the n8n instance terminates the connection. A temporary network interruption followed by automatic reconnection is considered part of the same session.

Allow for session rules persist across such re-connections and are cleared only when the session ends.

---

Startup Configuration

Permission Setup

Before the gateway connects, the user must configure the permission mode for each tool group. The gateway will not start unless at least one tool group is enabled (Ask or Allow).

CLI — An interactive prompt lists each tool group with its current mode. If a valid configuration already exists the user can confirm it with y or edit individual modes before proceeding.

Native application — The user sees an equivalent configuration UI.

Filesystem Root Directory

When any filesystem tool group (Filesystem Access or Filesystem Write Access) is enabled, the user must specify a root directory. The AI can only access paths within this directory — all operations on paths outside are rejected. This applies to both read and write operations.

Configuration Templates

To simplify first-time setup, three templates are available. When no configuration file exists the user selects a template before editing individual modes.

Template	Filesystem Access	Filesystem Write Access	Shell Execution	Computer Control	Browser Automation
Recommended (default)	Allow	Ask	Deny	Deny	Ask
Yolo	Allow	Allow	Allow	Allow	Allow
Custom	User-defined	User-defined	User-defined	User-defined	User-defined

Regardless of template, the filesystem root directory must always be provided when any filesystem capability is enabled.

Configuration File

The gateway configuration is stored in a file managed by the Local Gateway application. Whether the configuration persists across restarts depends on whether the process has OS-level write access to that file — this is independent of the permission model for tools. If write access is unavailable the configuration is active only for the lifetime of the current process.

The configuration file stores:

• Permission mode per tool group
• Filesystem root directory (required when any filesystem capability is enabled)
• Permanently stored resource-level rules (always allow / always deny)