Starlink API Tooling

This package is not affiliated with or acting on behalf of Starlink™️

Requirements

• Node.js >= 22

Installation

npm install @gibme/starlink
Copy

or

yarn add @gibme/starlink
Copy

Features

Local Device API (gRPC)

Communicate directly with Starlink hardware on your local network via gRPC.

• Dishy (Satellite Dish)
  • fetch_diagnostics() - Detailed diagnostics including alerts, tests, and location
  • fetch_status() - Current device status
  • fetch_history() - Connection history data
  • fetch_location() - GPS location (requires location enabled in dish settings)
  • fetch_obstruction_map() - Obstruction map data
  • reboot() - Issue a reboot command
  • stow() / unstow() - Stow or deploy the dish
• WiFi Router
  • fetch_diagnostics() - Router diagnostics and network information

Enterprise API (Enterprise API Access Required)

Full enterprise account management via the Starlink REST API.

• Account Management - Fetch and manage enterprise accounts
• Address Management - Create, fetch, update addresses; check service capacity at a location
• Service Lines - Create, fetch, and remove service lines; fetch daily usage and billing periods
• User Terminals - Add, fetch, and remove terminals; search by UT ID, serial, or kit serial
• Router Configuration - Create, fetch, update, and deploy router configs
• Products & Billing - Fetch available subscription products and real-time data usage tracking
• Telemetry - Stream real-time device telemetry including router telemetry, terminal telemetry, data usage, IP allocations, and active alerts

Subpath Imports

The package provides focused entry points for tree-shaking or targeted imports:

Import Path	Description
@gibme/starlink	Full API (enterprise + local devices + utilities)
@gibme/starlink/enterprise	Enterprise API only
@gibme/starlink/dishy	Local Dishy device API only
@gibme/starlink/wifirouter	Local WiFi Router device API only

Utility Functions

• gpsTimeToUTC(gpsTimeS) - Convert GPS time (seconds since 1980-01-06 UTC) to a UTC timestamp
• gpsTimeToUTCDate(gpsTimeS) - Convert GPS time to a Date object in UTC

Special Notice

• The package build process generates TypeScript code from *.proto definitions into ./src/protobuf/spacex

  • The protoc binary is required to build the TypeScript files
    • Ubuntu: apt install protobuf-compiler
    • Mac OSX: brew install protobuf
    • Windows: choco install protoc
  • If you are working on this package, or load this package from git, you will need to manually run yarn build:protobuf to generate the protobuf code

• The Device API calls listed above were tested as working against the following software versions; for all other versions, your mileage may vary:

  • Dishy
    • 186897dc-8910-40f9-bb84-c53a5e8404c9.uterm_manifest.release

Documentation

https://gibme-npm.github.io/starlink/

Sample Code

Dishy

import { Dishy } from '@gibme/starlink/dishy';

const dishy = new Dishy();

const diagnostics = await dishy.fetch_diagnostics();

console.log(diagnostics);
Copy

WiFi Router

import { WiFiRouter } from '@gibme/starlink/wifirouter';

const router = new WiFiRouter();

const diagnostics = await router.fetch_diagnostics();

console.log(diagnostics);
Copy

Reaching a local device through a reverse proxy (HTTPS + API key)

Both Dishy and WiFiRouter take a single options object. Supply tls to talk to a TLS-terminating reverse proxy, and headers to attach any extra headers (e.g., an API key) to every gRPC call:

import { Dishy } from '@gibme/starlink/dishy';

const dishy = new Dishy({
    host: 'dishy.example.com',
    port: 443,
    timeout: 5000,
    tls: true,
    headers: { 'x-api-key': process.env.DISHY_API_KEY! }
});
Copy

tls: true uses the system trust store with strict hostname verification. For private CAs or self-signed development proxies, pass an object instead:

import { readFileSync } from 'node:fs';

const dishy = new Dishy({
    host: 'dishy.lan',
    port: 9443,
    tls: {
        rootCerts: readFileSync('/etc/ssl/private-ca.pem'),
        rejectUnauthorized: true
    },
    headers: { 'x-api-key': 'secret' }
});
Copy

Setting rejectUnauthorized: false skips certificate verification entirely; only use that for trusted local development environments.

Enterprise API

import { StarlinkAPI } from '@gibme/starlink/enterprise';

const api = new StarlinkAPI('<client_id>', '<client_secret>');

const accounts = await api.fetch_accounts();

const data = await accounts[0].fetch_realtime_data_tracking();

console.log(data);
Copy

Telemetry Streaming

import { StarlinkAPI } from '@gibme/starlink/enterprise';

const api = new StarlinkAPI('<client_id>', '<client_secret>');

const accounts = await api.fetch_accounts();

const telemetry = await accounts[0].telemetry();

console.log(telemetry);
Copy

Thanks

Many thanks go to starlink-rs for the older version of the base Protocol Buffers definitions for the gRPC server.