Skip to main content

Gateway Language Server

Flint ships a full language server for Ignition Jython scripts, hosted by your live gateway. It knows the actual system.* API exposed by your gateway's installed modules and indexes your project's script library, so completion and navigation reflect your real environment — not a generic Python install.

The language server runs by default whenever a gateway with an API token is selected. It does not require a running Designer.

Prerequisites

Needs a configured gateway with an API token in flint.config.json, and the Flint Designer Bridge module v1.2.0 or newer installed on the gateway. A running Designer is not required. Without a selected gateway and token, the language server stays dormant and Flint falls back to offline completion.

How it works​

The language server runs inside the Flint Designer Bridge module on the gateway and speaks the Language Server Protocol over a WebSocket at /system/flint-lsp — the same port and TLS as the gateway's web interface, so it works through reverse proxies. There is no local server process: VS Code connects directly, authenticating with your gateway API token at the connection handshake.

Because the endpoint speaks standard LSP, any LSP-capable editor can use it — see Connecting from other editors.

Setup​

  1. Install the Flint Designer Bridge module v1.2.0+ on your gateway (see Module Installation).
  2. Add the gateway to flint.config.json and point modules.project-scan-endpoint.apiTokenFilePath at a file containing an API token:
{
  "gateways": [
    {
      "id": "my-gateway",
      "host": "gateway.example.com",
      "port": 8043,
      "ssl": true,
      "modules": {
        "project-scan-endpoint": {
          "apiTokenFilePath": "~/.flint/tokens/my-gateway-token.json"
        }
      }
    }
  ]
}

apiTokenFilePath may sit at gateway level as shown above, or inside a specific entry under environments when each environment uses a different token. The environment value wins where both are present. See Configuration.

  1. Select the gateway in the Flint status bar. The extension checks the gateway's Flint health endpoint and connects automatically.

If the gateway's module is older than v1.2.0, the language server stays off and Flint shows a one-time notice asking you to upgrade the module.

Getting a token​

The token type depends on your Ignition version:

Ignition versionToken typeHow to get it
8.1.44+Flint bearer tokenAuto-generated by the Flint module. The gateway writes a token file to <dataDir>/modules/flint/gateway/api-token.json on startup — copy it to your workstation, or set the FLINT_GATEWAY_API_TOKEN environment variable on the gateway to supply your own.
8.3.1+Native gateway API tokenCreate an API token in the gateway web interface (Config > Security > API Tokens) and save it to a file referenced by apiTokenFilePath.

The extension detects the gateway version and sends the token with the matching scheme automatically — Authorization: Bearer for Flint tokens, X-Ignition-API-Token for native tokens.

Language features​

FeatureBehavior
CompletionPosition-aware. system.* functions from the live gateway's ScriptManager, project script modules, local variables, and Python keywords.
HoverFunction signatures (parameter names) as markdown.
Go to definitionJumps within a file and across files into project script modules.
Find referencesIntra-file, best-effort identifier matching.
DiagnosticsJython syntax errors, reported as you type (source flint-jython).
SymbolsDocument symbols (outline) and workspace symbol search.

If your gateway hosts a single project, the language server selects it automatically; otherwise it uses the project associated with your selected gateway and workspace.

The connection restarts automatically when you switch gateways or projects, change the relevant configuration, or the gateway restarts — no reload required.

Precision limits
  • Hover shows function signatures only — no docstrings, no parameter types or defaults, and no hover for system.* functions.
  • Diagnostics are syntax-only. Undefined names, type errors, and other semantic problems are not reported.
  • Find references is best-effort and limited to the current file.
  • No completion for Java classes, tag paths, Perspective style classes, or view paths.

Connecting from other editors​

The endpoint is standard LSP over WebSocket, so editors other than VS Code can use it:

  • URL: wss://<gateway-host>:<port>/system/flint-lsp (ws:// for non-SSL gateways)
  • Auth: send your token as a header on the WebSocket upgrade — Authorization: Bearer <token> (Flint token) or X-Ignition-API-Token: <keyId:secret> (Ignition 8.3 native token). Connections without a valid token are rejected with HTTP 401.
  • Framing: standard LSP Content-Length framing, or one JSON message per WebSocket frame — the server auto-detects and mirrors whichever your client uses.
  • Project selection: pass initializationOptions: { "project": "<projectName>" } in the initialize request.

For editors that only launch stdio language servers (Neovim, Helix), bridge with any stdio↔WebSocket relay such as websocat:

websocat -b - wss://gateway.example.com:8043/system/flint-lsp \
  -H "Authorization: Bearer $TOKEN"

Configure your editor to launch that command as the language server — the server needs nothing Flint-specific beyond the auth header.

Verifying the gateway endpoint​

Check that a gateway advertises the language server:

curl -s https://gateway.example.com:8043/data/flint/health | jq '.capabilities, .lspWsPath'

A module with WebSocket LSP support lists "lsp.websocket" in capabilities and reports "lspWsPath": "/system/flint-lsp".

Settings​

SettingDefaultPurpose
flint.languageServer.enabledtrueTurns the gateway language server on or off. When off, Flint uses the offline/Designer completion providers instead.
note

Disabling the language server removes hover, go-to-definition, references, and diagnostics — those features exist only on this path. The fallback providers offer completion only. See Completion for how the fallback sources work.