Development Documentation
View as:

Local Tray App

The Fabric Dev tray app is the local half of the hybrid developer portal. It owns the loopback FastAPI UI (formerly launched via scripts/fabric-ui.cmd), handles fabric-dev:// deep links the cloud portal hands off to your browser, and posts heartbeats so /operations/agents knows you're online.

Replaces the legacy scripts/fabric-ui.cmd + pip install -r requirements.txt workflow. Old instructions are gone — install the tray app instead.

Install in 30 seconds

Download + run once from anywhere — it installs itself to %LOCALAPPDATA%\fabric-dev and auto-starts on login. Re-downloading + running again just updates in place.

  1. Download fabric-dev-tray.exe

  2. Double-click the downloaded fabric-dev-tray.exe.

    Windows SmartScreen will warn about an unrecognised publisher — click More info → Run anyway. This is expected for an unsigned exe; no Developer Mode or administrator rights required.

  3. The tray icon (a blue "F") appears in the system tray.

    On first launch the app automatically:

    • Copies itself to %LOCALAPPDATA%\fabric-dev\fabric-dev-tray.exe (the canonical install location).
    • Registers itself to start at every user login (HKCU\Software\Microsoft\Windows\CurrentVersion\Run), pointing at the canonical location.
    • Registers the fabric-dev:// URL scheme so the cloud portal's deep links reach your machine (HKCU\Software\Classes\fabric-dev).
    • Relaunches from the canonical location and exits the Downloads copy.

    All registrations use HKCU — no admin elevation needed.

    Running the downloaded exe again (e.g. after re-downloading) copies the new version over the canonical location and relaunches from there — only one instance ever runs.

macOS / Linux

Not yet packaged. Run from source until packaging lands:

git clone <repo>
cd fabric_monorepo
pip install -r requirements.txt
python -m scripts.fabric_ui.tray

First launch

  1. Right-click tray icon → Sign in (az login). A new console opens; complete the device-code or interactive flow against the Geris tenant. Token cache lives at ~/.azure/.
  2. Click any fabric-dev:// link in the portal — the tray pops a native folder picker on first use and asks for your fabric_monorepo checkout. The path is persisted at %APPDATA%/fabric-dev/config.json.
  3. Done. You will not be prompted again until you change machines.

Tray menu

ItemBehaviour
Open portalOpens https://docs.fabric-monorepo.geris.nl (or the cloud_portal_base_url set in deployment/dev.yml) in the default browser.
Show local UIOpens http://127.0.0.1:8765 — the loopback dashboard with every scripts/fabric form.
Pause / ResumeToggles a flag the JobRunner checks. While paused, the loopback UI returns 503 to every new submission and deep links queue. In-flight subprocesses run to completion.
Sign in (az login)Spawns az login in a fresh console. Use this when your Entra token expires.
Choose editorSubmenu of code / cursor / code-insiders (default: code). The choice persists to config.json.
Edit config.json…Opens config.json in the OS default editor for hand-editing.
QuitStops the uvicorn loopback cleanly and exits. Autostart fires again on next OS login.

fabric-dev:// URL scheme

The cloud portal hands work back to the tray via URLs. The tray validates every URL, refuses unknown actions, and pops an OS-native confirm dialog for anything destructive.

URLAction
fabric-dev://open-feature?slug=<x>&open_editor=trueEnsure worktree at .claude/worktrees/<slug> on branch feat/<slug>, open configured editor.
fabric-dev://start-claude?slug=<x>&skill=fabric-feature-startEnsure worktree, spawn claude /<skill> in a new console.
fabric-dev://dbt-build?target=local&model_selector=<sel>Run dbt build --target local --select <sel> in <repo>/dbt.
fabric-dev://pr?slug=<x>Run scripts/pr_prepare.sh --feature <slug> in the worktree.
fabric-dev://teardown-local?slug=<x>Destructive. OS confirm dialog, then git worktree remove + git branch -d feat/<slug>. Refuses if the branch has unmerged commits.
fabric-dev://show-job?job_id=<id>Find the running tray's port (scans 127.0.0.1:8765-8785) and opens /jobs/<id> in the browser.
fabric-dev://provision?slug=<x>&profile=local|full&env=dev|uat|prod&developers=<csv>[&seed_strategy=bronze|uat][&data_refresh=auto|force|none][&with_functions=true]Run scripts/provision_feature_env.sh locally for local or full profiles — terraform, workspaces, Bronze+Gold download into dev-data/, and local dbt. Emitted by the feature-env form for local/full profiles. Passing model or bronze is rejected with an informational message; use the cloud form instead.
fabric-dev://refresh-bronze-local?source=<env>-bronze&feature=<slug>&force=trueRefresh local Bronze Parquet mirror from the given source Lakehouse (dev-bronze, uat-bronze, or prod-bronze). Emitted automatically by the feature-env form after a successful bronze cloud provision.
fabric-dev://sync-gold-local?source=<env>&force=trueMirror a Fabric Gold Warehouse into dev-data/ via sync_cloud_parquets.py. Source is dev, uat, or prod. Run after refresh-bronze-local completes.

Unknown actions are logged to the tray's stderr and silently dropped.

Manual invocation (debugging)

python -m scripts.fabric_ui.fabric_dev_uri "fabric-dev://show-job?job_id=test"
python -m scripts.fabric_ui.fabric_dev_uri "fabric-dev://open-feature?slug=demo&open_editor=true"

The tray app's stderr / stdout are not surfaced in the frozen exe. To debug a failing URL, run the URI handler manually from a terminal — the same code path runs.

Build from source

For paranoid users who want to compile the exe themselves:

# Requires Python 3.11 + the project venv
git clone <repo>
cd fabric_monorepo
pip install -r requirements.txt
pip install pyinstaller

.\packaging\windows\build_exe.ps1
# Output: packaging/windows/dist/fabric-dev-tray.exe

To also publish to blob storage (requires az login + Storage Blob Data Contributor):

.\packaging\windows\build_and_publish.ps1
# Published: https://gerisdbtartifacts.blob.core.windows.net/installers/fabric-dev-tray-latest.exe

Migration from scripts/fabric-ui.cmd

scripts/fabric-ui.cmd is retired. Phase 8 of the hybrid portal rollout removed the legacy launcher. Install the tray app instead.

If you previously launched the loopback dashboard by double-clicking scripts/fabric-ui.cmd, install the tray app. The loopback UI itself is unchanged — same port, same forms, same job DB; the tray just owns its lifecycle and adds the URL-scheme handler.

Related