Skip to content

SkyNode gateway

The sky-node-gateway is a Skynet-internal service that brokers the bidirectional command and telemetry flow between the public API and the fleet of distributed SkyNode installations. It runs as its own FastAPI process at apps/sky-node-gateway/ and typically listens at port 5002 in dev (gateway_api_server in SkyNodeConfig).

This page is for developers who might think they need to talk to the gateway directly. In almost every case, you don't — public-api is the right surface for integrations.

When you need the gateway vs. the public API

You want to… Use
List observations, create observations, browse observatories, retrieve files public-api (REST API by domain)
Subscribe to live device snapshots, send a manual command to a telescope, watch task progress public-api WebSocket (WebSocket protocol)
Operate as a SkyNode installation reporting back to the hub sky-node-gateway (/v1/nodes/*)
Anything else public-api

The gateway is an internal-facing API for SkyNode installations. External developers building integrations against Skynet — scripts, custom dashboards, automated submission, alert subscribers — should target the public API and the public WebSocket. The gateway is documented here only because the line between "internal" and "external" looks blurry from the outside.

What the gateway exposes

The gateway has three router files at apps/sky-node-gateway/sky_node_gateway/routers/:

node.py — /v1/nodes/* (external to SkyNode, internal to the platform)

The HTTP RPC surface SkyNode installations use to report back to the hub. Includes:

  • Reporting observation task progress, results, and completion.
  • Uploading observation assets (the raw files an observation produces).
  • Querying the cached hardware graph (the same graph SkyNode also caches locally as part of SkyNodeConfig.hardware).

Authenticated via installation bearer tokens — the same OAuth flow SkyNode uses against auth-app. Not intended for use by anything other than a SkyNode install.

internal.py — /internal/* (infrastructure-only)

Internal-only routes used by other Skynet services (public-api, the schedulers, the file processors). Includes:

  • Tile fetch for processing pipelines.
  • Direct RPC proxying between public-api and SkyNode installations.

These routes are network-restricted and gated by internal request authentication. Not intended for any external caller.

ws.py — /v1/ws/* (WebSocket transport for SkyNode)

The bidirectional WebSocket the gateway uses to push commands from the hub down to SkyNode and to receive snapshots and events back up. Authenticated via installation bearer tokens.

This is not the same WebSocket surface external developers use. The external developer WS lives in public-api at apps/public-api/public_api/routers/ws.py — see WebSocket protocol.

Internal architecture

Three modules in apps/sky-node-gateway/sky_node_gateway/ worth knowing about:

  • connection_registry.py — tracks the set of currently-connected SkyNode installations and their WebSocket session state.
  • direct_rpc.py — the request/response proxy that lets a public-api call become a WebSocket round-trip to a specific SkyNode install.
  • database.py — shared with the rest of the platform (the gateway is its own Postgres user, skynet_gateway, but talks to the same database).

In summary

If you're building an external integration:

  • REST integration: the public API at port 5001. Use Getting started and the REST API by domain pages.
  • WebSocket integration: the public WebSocket at port 5001 under /v1/ws/. Use WebSocket protocol.
  • You are not building a SkyNode replacement. If you think you are, talk to the Skynet team first — there's almost certainly a better way to do what you're trying to do.