Documentation · QGIS plugin

Connection, operations and approvals in the plugin.

The plugin is the QGIS side of the system; projects, setup and support are provided by Geoinformatikbüro Dassau GmbH (GBD). It receives the calls from the bridge, checks every file path, puts far-reaching requests up for confirmation and returns state, images and files.

To the nine groups System and skills

Prerequisites

What has to be in place.

The plugin runs in QGIS Desktop from version 3.28 onwards. Use on Windows is experimental.

QGIS: Version 3.28 or newer with an open project; the plugin is installed as a ZIP and enabled in the plugin manager. The print templates of the qgis-print-layouts skill require QGIS 3.34 or newer.
CLI: Codex CLI, Claude Code or OpenCode, installed and logged in before the plugin starts it.
Working directory: A path that both QGIS and the CLI can reach. It is entered in the plugin settings.
Network: No inbound access required. The connection ends on the same machine.

Connection

WebSocket on 127.0.0.1, port 64876.

The bridge runs as a process of its own. The CLI talks to it over standard input, and the bridge holds the connection to the plugin. The far end is the loopback interface of the same machine.

Host   127.0.0.1
Port   64876
Token  shown, copied and regenerated in the plugin settings

The token is created in the plugin and taken from there into the CLI configuration. Binding to an address other than loopback requires token authentication and TLS together; without both the plugin refuses to start, because a token on an open line can be read by anyone listening.

Operations

Nine groups, 67 tools.

Every bridge tool corresponds to one handler in the plugin. The handlers sit in nine modules; the numbers below were counted on 18 September 2026.

Group	Count	Three examples
Project	3	`save_project`, `load_project`, `set_project_crs`
State	7	`get_qgis_state`, `get_layer_details`, `get_raster_statistics`
Layers	23	`load_layers`, `set_graduated_style`, `set_layer_labels`
Features	9	`select_features`, `get_attribute_values`, `edit_features`
Map	9	`map_navigation`, `get_map_screenshot`, `measure_distance`
Layouts	4	`load_layout_template`, `export_layout`, `list_layouts`
Jobs	3	`start_job`, `get_job_status`, `cancel_job`
Plugins	6	`list_plugins`, `install_plugin`, `set_plugin_enabled`
Files	3	`upload_to_qgis`, `download_from_qgis`, `list_files`
Total	67	Full signatures are in the `spatial-agent-bridge` skill.

Two further handlers fetch the remainder of truncated responses; they are part of the plugin but not a separate bridge tool.

Path rules

Every path is checked before QGIS sees it.

All tools that take a file path — image output, layout export, saving a style, saving the project, exporting a layer, file transfer, directory listing — consult the same gate before QGIS gets to see the path.

Allowed roots: The path is resolved and has to sit below a configured root. Otherwise the call ends with ACCESS_DENIED.
Overwriting: An existing file stays put: the call ends with FILE_EXISTS until it asks for the overwrite explicitly.
Reading from skills: The templates and styles of the bundled skills are readable in addition. Nothing is ever written there.
Remote sources: Addresses using http, https, WMS or WFS are not file paths and go to the network layer of QGIS.

Map images

Image and checksum.

A map image comes back as a Base64 PNG or is written into the working directory. Every image carries the SHA-256 checksum of its content.

The checksum answers a question that arises whenever a result is verified: has the image actually changed since the last edit? Two identical sums mean an identical image, whatever the file name and timestamp say. The same sum accompanies the images exported from a layout.

Asynchronous jobs

Long operations run as a job.

A synchronous call waits 60 seconds at most. Exports, image output from large layouts, saving the project and bulk edits to features exceed that; they are therefore started as a job and polled.

pending → running → completed
                 → failed
                 → cancelling → cancelled

A cancellation sets a flag that the running work checks at its stage boundaries; nothing is forced. Whatever has been produced up to that point is kept as a partial result. A job that finishes before it sees the flag counts as completed, because the work did happen.

Files

Transfer and directory listing.

In local operation both sides share the working directory and a transfer is unnecessary. In container mode, and for files outside the shared path, two tools move them in either direction.

Up: upload_to_qgis writes a file onto the machine running QGIS. Limit: 100 MB.
Down: download_from_qgis fetches a file back. Limit: 32 MB, because the content passes through memory in full.
Anything larger: What exceeds that is exchanged through the shared working directory.
Listing: list_files shows the contents of allowed directories, page by page and filtered by name pattern.

Principle

No arbitrary code runs inside QGIS.

What happens in QGIS happens through the nine groups above. The plugin has no handler for submitted Python code, and the bridge announces no such tool.

Computation takes place outside, in the shared working directory, and comes back as a file. That costs an intermediate step and buys two things: a failure in a computation cannot take the running QGIS session with it, and every intermediate result exists as a file that can be checked.

System and skills Geospatial API