Skip to content

Installing SkyNode

SkyNode is a Tauri desktop app — a single binary that wraps a Python backend and an Angular GUI. Install it on a machine that can talk to your hardware drivers (ASCOM on Windows, vendor SDKs on whatever platform the vendor supports, plain TCP/serial for native drivers).

The install path covers four things:

  1. Provision the telescope (or observatory) record on the hub.
  2. Install the SkyNode app on the SkyNode host machine.
  3. OAuth-pair the install with the hub — this creates the SkyNodeInstallation record that ties the install to your telescope/observatory.
  4. (Optional) Set up the local MQTT broker if you want internal observatory tools to subscribe to device telemetry directly.

The configuration values you'll set during these steps are described in detail in Configuration. This page focuses on the order of operations.

1. Provision the hub record

You can't pair SkyNode with the hub until the record it'll bind to exists. Make sure of one of:

  • Telescope node: the telescope's record exists in Skynet, owned by your organization. See Telescope.
  • Observatory node: the observatory's record exists, owned by your organization. See Observatory.

For brand-new observatories, follow Onboarding through step 4 first; come back here once the records are in place.

2. Install the SkyNode app

The desktop app is a Tauri build of apps/sky-node-desktop/. For day-to-day operators, install from a packaged release rather than building from source.

Install packaging: the canonical packaged release channel (signed installers, auto-update server) is (to be documented — currently SkyNode is installed from source during the React-port + signing-pipeline rollout).

For now, building from source on the SkyNode host:

# from the repo root
npm install
npm run start-skynode          # Angular GUI (live shipping path)
# or
npm run start-skynode-react    # React GUI port (in progress)

System requirements:

  • OS — Windows is the most-tested platform because ASCOM is Windows-only. macOS and Linux work for native and simulator drivers.
  • Python — managed via uv for the backend; bundled in the packaged release.
  • Network — outbound HTTPS to your hub's API and gateway endpoints. If you'll use the local MQTT broker, also reserve the broker's TCP/WebSocket port.

3. OAuth-pair with the hub

On first run, SkyNode walks you through a multi-step startup wizard (see Local GUI tour for screenshots). The relevant configuration values that get set during pairing live under hub in SkyNodeConfig:

{
  "hub": {
    "hub_id": "Skynet Global Telescope Network",
    "api_server": "https://api.skynetgo.org/",
    "gateway_api_server": "https://node.skynetgo.org/",
    "auth": {
      "method": "oauth",
      "auth_server": "https://auth.skynetgo.org/",
      "client_id": "skynode-client",
      "redirect_uri": "skynode://auth/callback",
      "scopes": []
    }
  }
}

For local dev the defaults point at http://127.0.0.1:5000/ (auth-app), :5001 (public-api), and :5002 (sky-node-gateway); for production deployments you'll point at the real Skynet hostnames.

The pairing flow:

  1. SkyNode opens the auth server in your browser using the OAuth authorization-code flow.
  2. You sign in as the user that owns (or has update rights on) the target telescope/observatory.
  3. The auth server redirects to skynode://auth/callback with a short-lived code; SkyNode exchanges the code for an access + refresh token.
  4. SkyNode then prompts you to pick the node binding — telescope or observatory — and selects the specific record from the list of options your account can see. This step writes a SkyNodeInstallation record on the hub and sets node_type, observatory_id, and (for telescope nodes) telescope_id in SkyNodeConfig.
  5. SkyNode pulls the hardware graph for that telescope/observatory — observatories, telescopes, instruments, devices, sites, filters, IP cameras, operational constraints — and caches it locally under hardware in SkyNodeConfig. This is what the configuration page later edits drivers against.

The SkyNodeInstallation record is what tells the hub "this install is alive and bound to that telescope." Subsequent task fetches, snapshot publishes, and file uploads all carry the install's bearer token.

4. (Optional) Local MQTT broker

If you want to publish device, constraint, and operational snapshots to a local MQTT broker (so on-site tools — dashboard PCs, status TVs, dome-control panels — can subscribe without going through the hub), configure the local_broker section.

The broker itself isn't shipped with SkyNode; you run your own (Mosquitto is a common choice). SkyNode connects as a client.

Minimal config:

{
  "local_broker": {
    "enabled": true,
    "host": "127.0.0.1",
    "port": 1883,
    "transport": "tcp"
  }
}

The defaults publish three channels:

  • device_snapshot — QoS 0, retained
  • constraint_snapshot — QoS 1, retained
  • operational_snapshot — QoS 1, retained

For TLS, auth, websocket transport, last-will configuration, and per-channel QoS overrides, see Configuration → Local broker.

5. Restart and verify

Restart SkyNode after the initial pairing. On startup, the lifecycle supervisor walks through a deterministic sequence and you should see, in the local GUI dashboard:

  • All bound devices come online (or fail with explicit error messages per device).
  • Constraint snapshots populate.
  • The hub publisher reports a healthy connection.
  • The last_sync_at field in SkyNodeConfig updates.

The website-side telescope detail page should now show the install as paired, with current snapshots flowing in.

If anything's failing, jump to Troubleshooting.