Setup & First Sync
Getting Live running involves three things: installing the app, installing a signed license file, and connecting your workbook through the onboarding flow. First sync happens automatically once the connection is established.
Install
macOS
Download the macOS app from the downloads page. It installs as a menu-bar application. On launch it checks your license and manages the rtmify-live runtime process.
Windows
Download the Windows bundle. It is portable — no installer. Place RTMify Live.exe and rtmify-live.exe in the same directory and run the tray app.
CLI / headless
The runtime can also be run directly without a native shell. This is useful for server-side or CI contexts.
rtmify-live [--port N] [--db path] [--no-browser] [--repo path] [--profile name]
Default port: 8000 (scans up to 8010 for a free port). Default DB: graph.db in the working directory. Omit --no-browser and Live opens the dashboard automatically.
CLI flags
| Flag | Description |
|---|---|
| --port <N> | Port to bind (default 8000, scans to 8010). |
| --db <path> | Path to the SQLite graph database (default: graph.db). |
| --no-browser | Start the server without opening the browser. |
| --repo <path> | Register a local repo for scanning. Repeatable. |
| --profile <name> | Regulatory profile: medical, aerospace, automotive, generic. |
| --inbox-dir <path> | Custom path for the test-results file-drop inbox. |
| license info [--json] [--license <path>] | Show the current license status and, optionally, payload details. |
| license install <path> | Verify and install a signed license file. |
| license clear | Remove the installed license file. |
| --license-status-json | Print license status as JSON and exit. |
| --license <path> | Use a specific signed license file for this run. |
| --version | Print the runtime version and exit. |
| --help | Print usage and exit. |
License install flow
Live no longer uses activation keys. It looks for a signed license.json file and, if one is not installed, starts in a gated state.
From the app
Use Select License File in the license gate. The native shell or dashboard imports the signed file and unlocks Live immediately if it is valid for the Live product.
Manual placement
Place the signed file at ~/.rtmify/license.json, or point a single run at a specific file with --license <path>.
If the file is expired, tampered, or issued for Trace instead of Live, the gate stays in place and the app shows the reason. Use license clear or the in-app clear action to remove an installed file.
What happens at startup
When rtmify-live starts, it does the following in order:
- Initialize the license service
- Handle fast-path commands (
license info,license install,license clear,--version,--help) and exit if matched - Open the SQLite database and store metadata (version, paths)
- Initialize secure credential storage
- Initialize test-results bearer-token authentication
- Establish the test-results inbox directory
- Migrate any legacy connection metadata
- Check license state and set product-gating
- Load any previously configured provider connection
- If licensed and connected: start the workbook sync thread
- Start the repo-scan thread
- Start the test-results inbox-polling thread
- Select a free loopback port (8000–8010)
- Store the selected port in config
- Optionally open the browser
- Start the HTTP server
Onboarding: connecting a workbook
If no provider is connected when Live starts, the dashboard shows the onboarding lobby. It walks through five steps:
- 1 Profile selection
Choose your regulatory context: medical, aerospace, automotive, or generic. The profile determines which extended tabs Live provisions and monitors.
- 2 Provider selection
Choose Google Sheets or Excel Online.
- 3 Credentials + workbook URL
Enter your credentials and the URL of the workbook. Details differ by provider — see below.
- 4 Review
Confirm the connection details before committing.
- 5 Success
Live validates the connection, persists credentials, and begins the first sync.
Google Sheets
You need a Google Cloud service account with access to the workbook.
| Field | What to provide |
|---|---|
| Service account JSON | The JSON key file downloaded from Google Cloud Console |
| Workbook URL | The full URL of the Google Sheets document |
Important: The onboarding screen shows you the service-account email extracted from the JSON. You must share the Google Sheet with that email address before Live can read it.
Excel Online
| Field | What to provide |
|---|---|
| Azure Tenant ID | Your Azure Active Directory tenant ID |
| Azure Client ID | The app registration client ID |
| Azure Client Secret | The app registration client secret |
| Workbook URL | The full SharePoint/OneDrive URL of the Excel workbook |
Credential security
Live does not store provider secrets in the SQLite database. Secrets are held in the platform-native secure store:
macOS
Keychain-backed secure storage
Windows
DPAPI-backed encrypted blob storage
SQLite stores only non-secret metadata: provider type, workbook URL, display label, and a credential reference. The secret payload never touches the database file.
If Live detects legacy plaintext credentials from an older version, it will not use them. The workspace will appear as requiring reconnect, and the dashboard will tell you why.
First sync
Once the connection is validated, Live begins syncing immediately. It:
- Provisions any missing tabs the profile requires (Design Inputs, Design Outputs, Configuration Items, RTMify Verification header)
- Reads all data tabs from the workbook
- Ingests rows into the in-memory graph using the shared schema layer
- Persists the graph to SQLite
- Computes and writes status values back to the workbook
- Applies row color formatting
After the first sync, Live polls for workbook changes every 30 seconds. It uses a change token (last-modified time from Google or from the Graph drive item) to determine whether to re-ingest. If the workbook hasn't changed, the cycle sleeps without doing any work.
Sync failures don't crash the runtime. Live records the error, backs off with exponential delay (30 → 60 → 120 → 300 seconds), and keeps retrying. The dashboard shows last-sync time and any error state.