Neovim LSP Client Architecture: Minimal Config, Trust Boundaries, and Operational Health

Requirements

Neovim includes a built-in LSP client that launches language servers as external processes over stdio or TCP. The practical problem is to get reliable code intelligence without adding a third-party client plugin, while keeping server selection, root scoping and health observable. The design must be declarative, testable with native Lua APIs, and treat servers as semi-trusted local processes.

Smallest Suitable Design

A minimal configuration maps filetype to a launch command and a project root, using only Neovim core APIs. No plugin manager is required. The configuration lives in init.lua and registers a FileType autocommand that starts a client when a buffer matches.

-- init.lua, Neovim 0.10+
local function start_lsp_for_buf(bufnr, name, cmd, root_markers, filetypes)
  local bufname = vim.api.nvim_buf_get_name(bufnr)
  if vim.tbl_contains(filetypes, vim.bo[bufnr].filetype) then
    local root = vim.fs.root(bufnr, root_markers)
    if not root then return end
    local client_id = vim.lsp.start_client({
      name = name,
      cmd = cmd,
      root_dir = root,
      capabilities = vim.lsp.protocol.make_client_capabilities(),
      single_file_support = true,
    })
    if client_id then
      vim.lsp.buf_attach_client(bufnr, client_id)
    end
  end
end

vim.api.nvim_create_autocmd('FileType', {
  pattern = 'python',
  callback = function(args)
    start_lsp_for_buf(args.buf, 'pyright', { 'pyright-langserver', '--stdio' },
      { 'pyproject.toml', 'setup.py', '.git' }, { 'python' })
  end,
})

vim.api.nvim_create_autocmd('FileType', {
  pattern = { 'typescript', 'typescriptreact', 'javascript', 'javascriptreact' },
  callback = function(args)
    start_lsp_for_buf(args.buf, 'tsserver', { 'typescript-language-server', '--stdio' },
      { 'package.json', 'tsconfig.json', '.git' },
      { 'typescript', 'typescriptreact', 'javascript', 'javascriptreact' })
  end,
})

vim.diagnostic.config({ virtual_text = true, signs = true, underline = true })

The root_dir function scopes the server to a project directory. The server can only see files under that root. The design is declarative because filetype, command and root markers are explicit.

Trust and Data Boundaries

Language servers run as separate processes with the same user privileges as Neovim. They can read any file under the detected root, execute tools, and return diagnostics. Treat them as semi-trusted.

• Server selection is security relevant. Prefer servers with documented privacy policies and no default telemetry upload. Audit server behavior before enabling in sensitive repositories.
• Root-directory scoping limits exposure. Use conservative root patterns and avoid falling back to filesystem root.
• Network exposure is a boundary. Stdio is preferred. If TCP is used, bind to 127.0.0.1 only.

For high sensitivity, run the server in a container with a read-only mount of the project.

Operational Health Checks

Verification uses built-in commands and Lua APIs.

Interactive checks

Run :checkhealth in normal mode. Review the LSP section for missing executables or configuration warnings. Run :LspInfo to list attached clients per buffer, negotiated capabilities and resolved root directory.

Programmatic check

:lua
local clients = vim.lsp.get_active_clients({ bufnr = 0 })
for _, c in ipairs(clients) do
  print(c.name, c.config.root_dir)
end

Run after opening a file of the target language. Expect at least one client with a non-empty root_dir. Required permission is normal Neovim user access. Risk is none; the call is read-only.

Failure Modes and Mitigations

Server startup timeout. Symptom is no client attached after FileType. Mitigation: validate the cmd exists with vim.fn.executable before start, and keep cmd simple with stdio.

Root-directory misdetection. Symptom is server attaching to wrong project or home directory. Mitigation: list root markers in order of specificity and avoid permissive fallbacks. Set single_file_support false for monorepos where needed.

Protocol version drift. Symptom is missing capabilities after a server upgrade. Mitigation: pin server versions in the toolchain and re-run :checkhealth after changes.

Duplicate diagnostics. Symptom is two servers reporting the same errors. Mitigation: scope activation by filetype and root, and avoid attaching multiple servers to the same buffer.

When a server crashes, Neovim remains responsive. Diagnostics clear automatically and a new start_client attempt occurs on the next buffer open.

Conditions That Change the Design

• Remote or containerized development. Stdio assumes local execution. Use a remote Neovim host inside the container or adapt transport to TCP with explicit forwarding.
• Policy-driven telemetry blocking. Wrap server launch in a wrapper script that strips telemetry flags or sets environment variables before exec.
• Multiple languages per buffer. Configure separate root_dir functions per server and enable single_file_support only where appropriate.

Limitations

LSP APIs and defaults change across Neovim releases. Verify against the exact version deployed. Language servers may send telemetry depending on implementation; audit each server. Multiple servers on one buffer can produce conflicting diagnostics; strict filetype-root scoping avoids this.

Practical Result Check

Open a representative project, e.g., a Python repo with pyproject.toml. Run :LspInfo. The output should list one client for that buffer with the expected root directory and a non-empty capabilities table. If missing, run :checkhealth to locate a missing executable or root pattern mismatch. Stop the server externally and confirm Neovim stays responsive and reattachment succeeds on next buffer open.