Skip to main content

Quick Start

Get an OpenSynaptic node running in under 5 minutes.

Prerequisites​

RequirementVersion
Python3.10 or later
OSWindows 10/11, Linux, macOS
Disk space~50 MB

Step 1 — Clone and Install​

git clone https://github.com/OpenSynaptic/OpenSynaptic.git
cd OpenSynaptic
pip install -e .

Verify installation:

os-node --help

Step 2 — Run the Demo (One Command)​

The demo command starts a local virtual sensor loop and opens the web dashboard automatically:

os-node demo --open-browser

This will:

  1. Create a temporary Config.json in memory (no files written)
  2. Start the web_user plugin at http://127.0.0.1:8765/
  3. Generate virtual sensor packets (temperature, pressure, voltage) every 2 seconds
  4. Open your browser to the management dashboard

You should see the live dashboard with panels for device identity, transport status, pipeline metrics, and plugin state.

Press Ctrl+C to stop.

Step 3 — Create a Persistent Config​

Use the wizard to generate a Config.json for a real node:

os-node wizard

Or use defaults immediately:

os-node init --default

This creates Config.json in the current directory with safe defaults:

{
  "device_id": "MY_NODE_01",
  "VERSION": "1.3.1",
  "engine_settings": { "precision": 6 },
  "RESOURCES": {
    "transporters_status": { "udp": true },
    "service_plugins": {
      "web_user": { "enabled": true, "port": 8765 }
    }
  }
}

Step 4 — Start the Node​

os-node run --config Config.json

The node runs indefinitely, sending heartbeats and processing sensor data.

For a one-shot test cycle:

os-node run --config Config.json --once

Step 5 — Start the Web Dashboard​

os-node web-user --cmd start -- --host 127.0.0.1 --port 8765 --block

Then open http://127.0.0.1:8765/ in your browser.

Alternatively use the standalone alias:

os-web --cmd start -- --host 127.0.0.1 --port 8765 --block

Step 6 — Send a Sensor Reading​

os-node transmit --config Config.json --sensor-id V1 --value 3.14 --unit Pa --medium UDP

This encodes the reading through the full pipeline (standardize → compress → fuse → send) and dispatches it via UDP.

Step 7 — View Node Status in the Terminal​

# Full snapshot across all sections
os-node tui --config Config.json

# Single section (identity, config, transport, pipeline, plugins, db)
os-node tui --config Config.json --section transport

# Live interactive mode (Ctrl+C to stop)
os-node tui --config Config.json --interactive --interval 2.0

Step 8 — Inspect and Edit Config​

# View all config
os-node config-show --config Config.json

# Read one key
os-node config-get --config Config.json --key engine_settings.precision

# Write a value
os-node config-set --config Config.json --key engine_settings.precision --value 8 --type int

# Write a sub-object in one command
os-node config-set --config Config.json --key RESOURCES.transport_config.quic \
  --value '{"port":4433,"timeout":3.0}' --type json

Common Command Reference​

GoalCommand
One-command demo with browseros-node demo --open-browser
Generate config with wizardos-node wizard
Generate config with defaultsos-node init --default
Run node loopos-node run --config Config.json
One-cycle test runos-node run --config Config.json --once
TUI snapshotos-node tui --config Config.json
TUI live modeos-node tui --config Config.json --interactive
Start web dashboardos-web --cmd start -- --host 0.0.0.0 --port 8765 --block
Send a sensor valueos-node transmit --config Config.json --sensor-id S1 --value 1.0 --unit Pa --medium UDP
Enable a transporteros-node transporter-toggle --config Config.json --name udp --enable
List pluginsos-node plugin-list --config Config.json
Check native libsos-node native-check
Build native libsos-node native-build

If Native Libraries Are Missing​

On first run, the node will attempt to build native C bindings automatically. If the build fails (e.g. no C compiler), you see a structured error and the node falls back to Python-only mode.

Manual fallback:

os-node native-check         # diagnose environment
os-node native-build         # attempt build with progress output

What To Do Next​

I want to...Go to...
Understand the full CLIinternal/CLI Reference
Use the Web API from scriptsguides/Web API Reference
Understand TUI sectionsguides/TUI Quick Reference
Build a pluginplugins/Plugin Starter Kit
Add a new transport protocolTRANSPORTER_PLUGIN.md
Understand the architectureARCHITECTURE.md
View API referenceAPI.md

Need Help?​

Last updated: 2026-04-02 (local workspace)