starlink-grpc-tools and the case for reading your dish directly

The dish has a gRPC service and the scripts speak to it directly

The repository holds a handful of tools for interacting with the gRPC service implemented on the Starlink user terminal, the dish. The important word is implemented: the service is there, exposed on the local network, and these scripts are a client for it.

That is why the project exists and why it is a set of scripts rather than a library. The Starlink app on your phone and the browser app at 192.168.100.1 both talk to the same service, and the scripts do the same thing but write the result somewhere you chose.

The data comes in two flavours, and the documentation draws the line for you. The status data is mostly what appears in the Debug Data section of the Starlink app, and most of the data on the app's Statistics page comes from the history data. You select which groups you want by naming their modes on the command line, and running a script with the -h option lists the available modes. The documentation at the top of starlink_grpc.py explains what each field means within each mode group.

A request for all currently available status groups looks like this:

python3 dish_grpc_text.py status obstruction_detail alert_detail

So the workflow is: pick the data groups, pick the destination, and the script does the gRPC conversation and the writing.

Six scripts, six destinations, one interface

The gRPC script set is the part being actively developed, and it is six files that mostly do the same thing with a different output backend.

dish_grpc_text.py writes to standard output. dish_grpc_influx.py and dish_grpc_influx2.py send to an InfluxDB 1.x and 2.x server respectively. dish_grpc_sqlite.py writes to a SQLite database. dish_grpc_mqtt.py sends to an MQTT broker. And dish_grpc_prometheus.py writes nowhere at all but listens for HTTP requests and returns data in a format Prometheus can scrape.

That last one is a different model from the others. The other five are push, and Prometheus is pull, so a script that exposes an HTTP endpoint for a scraper is not the same shape of program as one that opens a connection to a database.

The text script is the default in CSV format, and the -v option switches it to a slightly more human-readable format. That is the one to reach for first when you are exploring, since the other five all assume you have decided what to do with the data already.

By default, most of these scripts pull the data once, send it off to the specified backend, and exit. The documentation notes that they can instead be set to keep running and repeat, which is what turns them from a command you run into something you leave going.

The hard prerequisite is the fixed address the dish answers on

Everything in this project assumes one thing about your network, and it is worth understanding before anything else.

All the tools that pull data from the dish expect to reach it at the dish's fixed IP address of 192.168.100.1, and the Starlink Android app, iOS app and the browser app you can run directly from that same address all rely on the same thing. When you use a router other than the one included with the Starlink installation kit, this usually requires additional router configuration to make it work.

The documentation is realistic about the diagnosis. That configuration is beyond the scope of the document, but if the Starlink app does not work on your home network, then neither will these scripts.

And it notes the flip side, which is the reason this is usable as a separate tool at all: you do not need the Starlink app installed to make use of these scripts. The dish and the scripts are enough, which means a headless setup with no phone in the loop is a valid configuration.

For an InfluxDB deployment, the container example shows the shape of it, with the backend host and port passed as environment variables and the container given an address on your network:

# docker run -d --name='starlink-grpc-tools' -e INFLUXDB_HOST=192.168.1.34 -e INFLUXDB_PORT=8086 -e INFLUXDB_DB=starlink
# --net='br0' --ip='192.168.1.39' ghcr.io/sparky8512/starlink-grpc-tools dish_grpc_influx.py status alert_detail

Installing is either a container or a virtual environment

There are two routes, and the container route is much lighter on requirements.

With Docker or Podman, you skip the Python prerequisites entirely, and the only things you need are Docker itself and the dish address being reachable. The Dockerfile builds from a python:3.12 base and installs a pinned set of dependencies, including grpcio at 1.76.0, the InfluxDB client at 1.50.0, paho-mqtt at 2.1.0 and protobuf at 6.33.4. It copies the dish scripts and the entrypoint into /app and defaults to running the InfluxDB script for status and alert detail.

For local Python use, the requirement is Python 3, version 3.7 or later, and the distribution package should be fine. The modules come from a single command:

pip install --upgrade -r requirements.txt

The guide notes that this installs the latest versions of a superset of the required modules, and that if you want the minimum set or want to know which module is needed for what, there is a wiki article breaking the dependencies down per usage.

One practical wrinkle is called out. Some operating system Python installations require the use of a virtual environment when you run as root or Administrator, so the recommendation is to create and use a venv, and if you would rather not deal with that, either install as a different user or add the --user option after the word install, which makes the packages available only to that user.

The location data is already gone, and the guide says so

There is a section on enabling access to location data that carries a warning that changes how you should read it.

The note says that as of 2026-May, location data is no longer available via gRPC for most service plans, so the following instructions likely will not do anything useful. The section is only relevant if you want to use the location data group with the gRPC scripts, and it warns that enabling it allows any device on your local network to access the physical location data for your dish. If you are not comfortable with that, do not enable it.

The procedure itself is a good illustration of the fragility of this whole approach. Access to location data must be enabled per dish, and as of 2022-Sep this can only be done using the Starlink mobile app, version 2022.09.0 or later. It cannot be done using the browser app. You log in to your Starlink account by pressing the user icon in the upper left corner of the main screen, select SETTINGS, then ADVANCED, then DEBUG DATA, and find a toggle for allow access on local network in a section labelled STARLINK LOCATION, which should be off by default. The guide says this may move in the future and there is no guarantee the ability will remain in the app.

And a warning that is worth repeating to yourself: the Starlink mobile app can be pretty finicky and painfully slow, and it is best to wait for the screens to load completely before going on to the next one.

So a feature documented in detail turns out to be mostly a historical note, and the documentation says so in the first line rather than at the end.

What is actually being maintained, and what is a relic

The usage section says plainly that of the three groups of scripts, the grpc scripts are really the only ones being actively developed, and that the others are mostly by way of example of what could be done with the underlying data.

The repository root shows the full spread of those other scripts. There is dish_check_update.py, dish_common.py, dish_control.py, dish_json_text.py, dish_obstruction_map.py, dump_dish_status.py, extract_protoset.py, loop_util.py, poll_history.py, starlink_grpc.py and starlink_json.py, alongside the six active gRPC scripts, plus directories for dashboards, packaging, systemd and tests.

The two protocol families are worth noting because they are different approaches to the same dish. The gRPC set is the current one, and the JSON set is the older path, with the grpc and json prefixes in the filenames making the distinction obvious. extract_protoset.py and the note that generating the gRPC protocol modules is no longer required and is not particularly recommended, with the details moved to a wiki article, show that the generated protocol work has been folded in.

The requirements file lists the module set, including grpcio, grpcio-tools, protobuf, yagrc, paho-mqtt, the InfluxDB client, pypng, typing-extensions, croniter and python-dateutil.

The licence is the Unlicense, which is as permissive as a licence gets, and the release history is active: v1.2.4 on 2026-01-28, v1.2.5 on 2026-03-22 and v1.3.0 on 2026-10-12, with the last push the same day. The project describes itself in one line as random scripts and other bits for interacting with the SpaceX Starlink user terminal hardware, and that self-description is accurate.

Editorial conclusion

starlink-grpc-tools suits a Starlink owner who wants their own data in their own monitoring stack, particularly with InfluxDB and Grafana already running, because the scripts cover the dish side and leave the storage side to you. It does not suit someone who needs a supported integration, since there is none here and the project describes itself as random scripts, and it does not suit a plan that depends on location data, which stopped being available over gRPC for most service plans as of 2026-May. Before you build a dashboard on this, confirm the dish is reachable at its fixed address 192.168.100.1, keep the version pinned rather than tracking the default branch, and note that the last push was on 2026-10-12 with release v1.3.0 published the same day.

Frequently asked questions

Official sources

1. Issues
2. License: Unlicense
3. README
4. Releases
5. sparky8512/starlink-grpc-tools on GitHub