Skyfeed Client

Skyfeed Client runs on an ADS-B feeder host next to readsb or dump1090. It reads the local Beast stream, usually 127.0.0.1:30005, and connects outbound to a Skyfeed collector over WebSocket/TLS.

readsb/dump1090 :30005
  -> skyfeed-client
  -> wss://skyfeed.skyalgorithm.cloud/feed

The feeder host does not need inbound ports, VPN, or router port forwarding.

Prerequisites

• Linux host running readsb or dump1090
• Beast output available on 127.0.0.1:30005
• Docker Engine
• receiver_id and token from SkyAlgorithm

Recommended Install

Use Docker Compose with a local .env file. This keeps the receiver token visible in one place and makes updates/restarts easier.

Use the published image. Do not build on the feeder host.

sudo mkdir -p /opt/skyfeed-client
cd /opt/skyfeed-client

sudo curl -fsSLO https://raw.githubusercontent.com/SkyAlgorithm/skyfeed-client/main/deploy/feeder/docker-compose.yml
sudo nano .env

Paste:

SKYFEED_COLLECTOR_URL=wss://skyfeed.skyalgorithm.cloud/feed
SKYFEED_RECEIVER_ID=<receiver-id>
SKYFEED_TOKEN=<receiver-token>
SKYFEED_BEAST_HOST=127.0.0.1
SKYFEED_BEAST_PORT=30005

Start:

sudo docker compose --env-file .env up -d

Check logs:

sudo docker compose logs -f client

Expected successful startup:

connecting collector=wss://skyfeed.skyalgorithm.cloud/feed beast=127.0.0.1:30005 receiver=<receiver-id>
connected receiver=<receiver-id>

Upgrade:

cd /opt/skyfeed-client
sudo docker compose pull
sudo docker compose --env-file .env up -d

Stop:

cd /opt/skyfeed-client
sudo docker compose down

Quick Test

For a short test, you can run the container directly without Compose.

sudo docker run -d \
  --name skyfeed-client \
  --restart unless-stopped \
  --network host \
  -e SKYFEED_COLLECTOR_URL=wss://skyfeed.skyalgorithm.cloud/feed \
  -e SKYFEED_RECEIVER_ID=<receiver-id> \
  -e SKYFEED_TOKEN=<receiver-token> \
  -e SKYFEED_BEAST_HOST=127.0.0.1 \
  -e SKYFEED_BEAST_PORT=30005 \
  ghcr.io/skyalgorithm/skyfeed-client:latest

The container uses host networking so 127.0.0.1:30005 reaches the host's local Beast stream.

Check logs:

sudo docker logs -f skyfeed-client

Expected successful startup:

connecting collector=wss://skyfeed.skyalgorithm.cloud/feed beast=127.0.0.1:30005 receiver=<receiver-id>
connected receiver=<receiver-id>

Docker stores SKYFEED_TOKEN in the container config when using docker run. For long-term use, prefer the Compose setup above so the token is kept in /opt/skyfeed-client/.env.

Stop:

sudo docker rm -f skyfeed-client

Update:

sudo docker pull ghcr.io/skyalgorithm/skyfeed-client:latest
sudo docker rm -f skyfeed-client
# run the docker run command again

Security Notes

• Treat SKYFEED_TOKEN like a password. Do not share it.
• Docker requires root-level privileges to start containers. The examples use sudo so this is explicit.
• The container is not privileged.
• The container does not mount host directories.
• The container does not expose inbound ports.
• Host networking is used only so the client can read the local Beast stream at 127.0.0.1:30005.
• The container process runs as nobody inside the image.

Troubleshooting

• Connection refused to 127.0.0.1:30005: Beast output is not enabled or readsb/dump1090 is not running.
• WebSocket rejected or closes immediately: check SKYFEED_RECEIVER_ID and SKYFEED_TOKEN.
• DNS/TLS errors: check internet access and that the collector URL is exactly wss://skyfeed.skyalgorithm.cloud/feed.
• Connected but no aircraft: the local Beast stream may be empty or the receiver has no current traffic.

Message Contract

The client sends:

• Authorization: Bearer <token>
• X-Receiver-ID: <receiver_id>
• binary WebSocket messages containing raw Beast bytes
• JSON heartbeat messages

The collector endpoint is:

wss://skyfeed.skyalgorithm.cloud/feed