sos device connect
Connect device to local development server
Description
Establishes a connection between a signageOS device and the local development environment, allowing real-time testing and debugging of applets during development. Supports both local network (LAN) and forward server connections for different network configurations.
The command sets up a development server and configures the device to load the applet from the local machine, enabling hot reload and live debugging capabilities.
Usage
sos device connect [options]
Options
| Option | Type | Description | Default |
|---|---|---|---|
--no-default-organization | boolean | Prevent using the defaultOrganizationUid from ~/.sosrc | |
--organization-uid | string | Organization UID | |
--device-uid | string | Device UID | |
--applet-uid | string | Applet UID | |
--server-public-url | string | Public url of local machine server. Is useful when the local machine is behind a reverse proxy. | |
--server-port | number | The custom server port for local machine server. Default is detected from currently running applet server. | |
--force | boolean | Force start applet server even if it is already running on a different port. Kill the running server first. | |
--use-forward-server | boolean | Use forward server to connect to the device instead of the local network (LAN). It's useful when the device is not in the same network as the local machine. | |
--detach | boolean | Detach the applet HTTP server process from the terminal. Useful when want to run more commands reusing the same http server for current applet. | false |
--forward-server-url | string | Url of forward server to connect to the device instead of the local network (LAN). | `` |
--hot-reload | boolean | Enable hot reload and build of applet | false |
--applet-path | string | Path to the applet file or the project folder depending on the entry file. Relative to the command or absolute. |
Examples
# Connect device with basic configuration
sos device connect --device-uid device123 --applet-uid my-applet
# Connect with custom server port
sos device connect --device-uid device123 --server-port 8080
# Connect using forward server (for remote devices)
sos device connect --device-uid device123 --use-forward-server
# Connect with hot reload enabled
sos device connect --device-uid device123 --hot-reload
# Connect with custom organization
sos device connect --device-uid device123 --organization-uid org456
# Connect with custom public URL
sos device connect --device-uid device123 --server-public-url https://my-domain.com
# Connect and run in background
sos device connect --device-uid device123 --detach
# Force connection (terminate existing servers)
sos device connect --device-uid device123 --force
Advanced Usage
Prerequisites
Before connecting a device:
- Build and upload applet: The applet must be built and uploaded to the platform at least once
- Device configuration: Ensure the device is properly configured and accessible
- Network access: Device should be accessible via local network or use
--use-forward-serverfor remote access
Development Workflow
# Typical development workflow
sos applet generate --name my-applet
cd my-applet
npm run build
sos applet upload
sos device connect --device-uid device123 --hot-reload
Network Considerations
- Local Network (LAN): Default behavior, requires device and development machine on same network
- Forward Server: Use
--use-forward-serverwhen device is remote or behind different network - Custom Forward Server: Override with
--forward-server-urlfor private deployments - Public URL: Set
--server-public-urlwhen behind reverse proxy or custom domain
Configuration Tips
# Update package.json with applet UID when created
sos device connect --device-uid device123 --update-package-config
# Use custom ports for development
sos device connect --device-uid device123 --server-port 8080
# Run server in background for multiple sessions
sos device connect --device-uid device123 --detach
Since
0.9.0
Global Options
All commands support the following global options:
| Option | Alias | Description |
|---|---|---|
--help | -h | Display help information for any command |
--version | -v | Display the installed version of the CLI |
--api-url | -u | Override the API URL for REST requests |
--profile | Use a specific profile from ~/.sosrc config |
Examples
# Show version
sos --version
# Get help for any command
sos applet --help
sos applet upload --help
# Use custom API endpoint
sos --api-url https://api.example.com applet upload
# Use specific profile
sos --profile production organization list