How to Configure the Python Sidecar FastAPI Server for Offline Geoprocessing

To configure GeoLibre's Python sidecar FastAPI server for offline geoprocessing, install the optional extras with pip install "geolibre[all]", set the GEOLIBRE_CONVERSION_ROOTS environment variable to a local directory, and verify that the server binds to 127.0.0.1 with per-launch authentication tokens.

GeoLibre is an open-source geospatial desktop application that uses a Python FastAPI sidecar for local processing. The sidecar, located in backend/geolibre_server/, runs entirely on 127.0.0.1 and is launched by the Tauri desktop wrapper. Configuring it for offline operation ensures that all vector, raster, and conversion workflows execute without external network dependencies.

Install Optional Dependencies for Offline Processing

The FastAPI server defined in backend/geolibre_server/geolibre_server/app/main.py can only perform geoprocessing when the underlying Python libraries are available. These dependencies are not included in the base installation to keep the package lightweight.

Install the full set of processing backends using the all extra:

# Install all optional processing dependencies (GeoPandas, Shapely, rasterio, etc.)

pip install "geolibre[all]"

If you are using conda, install the base package from conda-forge first, then add the pip extras:

conda install -c conda-forge geolibre
pip install "geolibre[all]"

These extras provide the heavy lifting for algorithms like WhiteboxTools and GDAL bindings, which operate entirely on local data without requiring internet access.

Configure Environment Variables for Offline Mode

Set Local Conversion Roots

The conversion endpoints in backend/geolibre_server/geolibre_server/app/conversion.py respect the GEOLIBRE_CONVERSION_ROOTS environment variable to determine where file conversion operations are permitted. By default, this points to ./data, but for offline workflows you should explicitly set it to a local directory you control:

export GEOLIBRE_CONVERSION_ROOTS=/path/to/local/data

This prevents the server from attempting to access or write to network-mounted drives or remote URLs during format conversions (e.g., GDB to GeoParquet).

Disable External Network Calls

The sidecar does not require external network access for its core algorithms. To guarantee offline operation, ensure the following configurations are in place:

• Prevent remote URL fetching – The FastAPI server respects the Jupyter configuration flag disable_check_xsrf defined in backend/geolibre_server/jupyter_server_config.py. Because the server runs behind a loop-back token, XSRF checks are safely disabled.
• Restrict to localhost – The server binds exclusively to 127.0.0.1 via c.ServerApp.ip = "127.0.0.1" in the Jupyter configuration, ensuring no external hosts can reach the API.

Verify Localhost Binding and Security Settings

The desktop app embeds the JupyterLab UI in an iframe with an origin of tauri://localhost (or http://tauri.localhost on Windows). The Content Security Policy (CSP) is defined in backend/geolibre_server/jupyter_server_config.py via the _FRAME_ANCESTORS tuple. This setting allows the Tauri shell to frame the Jupyter interface while keeping the server isolated from external traffic.

No modification is required for offline mode, but you can verify the configuration includes:

c.ServerApp.ip = "127.0.0.1"

This ensures the FastAPI instance in main.py is only accessible from the local machine, even when the host has active network interfaces.

Launch the Sidecar Without External Proxies

In the Tauri native code (src-tauri/src/lib.rs), the sidecar is launched using the built-in uv run --project command. For offline scenarios, ensure this launch command does not include --proxy flags or other network-dependent parameters:

// Example launch pattern in src-tauri/src/lib.rs
Command::new_sidecar("geolibre_server")
    .args(["--port", "0"]) // Random free port
    .env("GEOLIBRE_CONVERSION_ROOTS", "/local/data")
    .spawn()

The server starts on a random free port, and the desktop wrapper automatically embeds the URL http://127.0.0.1:<port>/ together with the per-launch authentication token handled by the Rust launcher.

Test Offline Geoprocessing Workflows

After starting GeoLibre in desktop mode, verify that processing algorithms execute without network access. The following Python code runs a Whitebox "buffer" algorithm on a local GeoJSON layer:

from geolibre import Map

# Create a map – the embedded sidecar starts automatically

m = Map(center=(-100, 40), zoom=4)

# Add a local GeoJSON file (no network access required)

m.add_geojson("data/roads.geojson", name="Roads")

# Run the Whitebox buffer algorithm on the "Roads" layer

result = m.run_algorithm(
    "buffer",
    {"layer": "Roads", "distance": 500},
    timeout=120
)

print("Buffer created, layer IDs:", result["resultLayerIds"])

To confirm the server is truly offline, monitor network connections while the app is running:

# Linux/macOS: Check for established connections excluding localhost

sudo lsof -i -n -P | grep ESTABLISHED | grep -v 127.0.0.1

If the output is empty, the sidecar is operating without external network calls. If an algorithm attempts to download remote resources, it will raise RuntimeError: offline environment – external fetch blocked, confirming the offline guard is active.

Summary

• Install processing extras with pip install "geolibre[all]" to enable local vector, raster, and conversion algorithms.
• Set GEOLIBRE_CONVERSION_ROOTS to a local directory to restrict file conversion operations to offline-accessible paths.
• Verify localhost binding in backend/geolibre_server/jupyter_server_config.py (c.ServerApp.ip = "127.0.0.1") to ensure the FastAPI server only accepts local connections.
• Launch via Tauri without proxy flags in src-tauri/src/lib.rs to prevent external network dependencies.
• Test with local data using Whitebox algorithms and monitor network connections to confirm offline isolation.

Frequently Asked Questions

Does the GeoLibre FastAPI sidecar require an internet connection to start?

No. The server binds to 127.0.0.1 and generates a per-launch authentication token, making it completely isolated to the local machine. It does not phone home or check for updates during startup, allowing it to launch and operate in fully air-gapped environments.

What Python packages are included in the geolibre[all] extra?

The all extra includes GeoPandas, Shapely, rasterio, WhiteboxTools, and other geoprocessing libraries required by the endpoints in backend/geolibre_server/geolibre_server/app/main.py. These packages perform the actual spatial analysis locally without external API calls.

How do I verify that no external network calls are being made?

Use system monitoring tools like lsof (Linux/macOS) or netstat (Windows) to inspect established connections while the app is running. Filter out localhost traffic (127.0.0.1); if no other connections appear, the sidecar is operating offline. Additionally, attempting to run algorithms on remote URLs will raise a RuntimeError indicating that external fetches are blocked.

Can I customize the Content Security Policy for the embedded iframe?

Yes. The CSP settings in backend/geolibre_server/jupyter_server_config.py control which origins can frame the JupyterLab interface via the _FRAME_ANCESTORS tuple. The default configuration allows tauri://localhost for the desktop shell. You can modify this if you have customized the Tauri scheme, though this is not required for offline functionality.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}