Skip to main content

Forward Server Bridge

Forward Server Bridge is a tunneling tool that exposes a local HTTP port to the internet through a public URL. It creates a WebSocket tunnel so that signageOS cloud services and devices can reach a server running on your development machine — even behind a firewall or NAT.

How signageOS Uses It​

You typically do not need to interact with the Forward Server Bridge directly. It is used under the hood by the signageOS CLI and SDK to establish connectivity between your local machine and remote devices.

Device Connect​

The sos device connect command can use the bridge to let a physical device load your locally served applet — even when the device is not on the same network as your machine. Pass --use-forward-server to enable tunneling:

sos device connect --device-uid <deviceUid> --hot-reload --use-forward-server

Without --use-forward-server, the device connects directly to your local machine (requires the same network). With the flag, the CLI creates a tunnel through the forward server so the device can reach your development server remotely.

Applet Serve​

When the SDK serves an applet locally (e.g., during sos applet start), it can forward the local applet server through the bridge so that remote devices can access it. The SOS_FORWARD_SERVER_URL environment variable controls which forward server is used.

Standalone CLI & SDK​

The bridge is also available as a standalone tool via the @signageos/forward-server-bridge npm package. You can use it as a CLI binary (via npx) or import it as a TypeScript SDK in your own scripts.

For full usage details, CLI options, SDK API reference, and connection recovery behavior, see the package README on npm.

Quick Start​

npx @signageos/forward-server-bridge \
  --local-port 3000 \
  --server-url https://forward.signageos.io

The command prints the public URL to stdout. The process runs until you press Ctrl+C. The CLI reconnects automatically with exponential backoff if the connection drops.