Setup & First Sync
There are currently two startup paths. The native shell apps on macOS and Windows manage the local runtime for you and can launch unlicensed in preview mode. The raw rtmify-live runtime can also be launched directly, and that path also runs in preview mode without a license. First sync happens automatically once a workbook connection is established.
Install
macOS
Download the macOS app from the downloads page. It installs as a menu-bar application, manages the rtmify-live runtime process, and allows you to start in preview mode when no license is installed.
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. When no valid license is installed, the tray app still starts and labels the session as preview mode.
Linux / CLI / headless
Linux is currently a direct-runtime distribution only. There is no Linux tray or menu-bar shell in this release. The runtime can also be run directly without a native shell on any platform, which is useful for server-side or CI contexts and operates in preview mode without a license file.
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. macOS, Windows, and the raw rtmify-live runtime can all start without that file in preview mode, where the workbook remains readable but licensed features stay disabled.
From the app
Use Install License File in the macOS or Windows shell. If the shell is already running Live in preview mode, it restarts the managed runtime and returns in licensed mode after a valid import.
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 import is rejected and the shell shows the reason without unlocking the app. Preview mode currently locks MCP, reports, repository scanning, code traceability, and background sync. 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, repo-scan thread, and test-results inbox-polling thread
- If unlicensed and connected: keep licensed routes gated and allow preview-mode workbook sync only
- 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
Linux
No supported secure-store backend yet. Direct runtime preview works, but workbook credential persistence is currently out of scope.
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.