Configuration¶
Day-to-day controls live in Settings. This page is the developer reference: environment variables and what is stored on disk.
Desktop vs browser¶
The packaged app (and make tauri-dev) starts a Python supervisor on 127.0.0.1 with an ephemeral port. The window receives a base URL and a session token. You do not set Twin/MRI ports by hand.
npm run dev still uses Vite proxies to :8080, :8001, and :8002.
The Google API key belongs in Settings → AI & Agents, which writes <app-config>/google_api_key. Do not put keys in the installer.
Optional Vite env¶
Create .env.local only if you must override defaults.
| Variable | Default | Purpose |
|---|---|---|
VITE_DTAM_API_URL |
/api/dtam |
Twin API |
VITE_ADK_API_URL |
/api/agents |
Agents API |
VITE_MRI_API_URL |
/api/mri |
MRI console API |
VITE_ADK_APP_NAME |
dtam |
ADK app name |
VITE_ADK_USER_ID |
gui-user |
Demo user for ADK sessions |
VITE_ADK_MODELS |
built-in list | Optional id:Label,... |
VITE_ADK_MODEL |
first model | Default model id |
VITE_MAGNET_CAD_URL |
unset | Legacy public URL for a single mesh |
Imported CAD no longer needs VITE_MAGNET_CAD_URL. Use Settings → 3D Model → Files.
Proxies (npm run dev)¶
/api/dtam → :8080, /api/agents → :8001, /api/mri → :8002 (WebSocket included). Vite is pinned to 5173 so Tauri can find it. Avoid port 3000 on lab machines that already run Grafana.
If you set an absolute VITE_DTAM_API_URL (no proxy), add the Vite origin to DTAM DTAM_CORS_ORIGINS.
DTAM runtime (desktop)¶
Saved as dtam_runtime.json in the app config directory:
| Field | Role |
|---|---|
scanner_id |
e.g. simulated_scanner |
environment |
e.g. development |
agent_model / agent_mode |
Gemini model and mode |
Scanner and environment changes update the Twin session without restarting other services. Agent settings still restart the Python runtime. A complete user configuration under the app-config dtam/ folder takes precedence over bundled defaults.
Device listener (devices.json)¶
Boards connect to a WebSocket port, not Twin HTTP (:8080). The Twin starts the listener when it finds devices.json. There is no UI Start control; restart after changing the file.
| Lookup | Path |
|---|---|
| Explicit | ADELPHA_DEVICE_CONFIG |
| Desktop | <app-config>/dtam/devices.json (Settings → Devices → Open config folder) |
| Also tried | <ADELPHA_CONFIG_DIR>/devices.json, <DTAM_CONFIG_DIR>/devices.json |
| Field | Role |
|---|---|
host / port |
Bind address. Use 0.0.0.0 so a Pi on Ethernet can connect. Default port 8765. |
allow_control |
File-level gate for actuators.set. Default false. |
devices.<id>.token |
Unique random Bearer token, at least 24 characters |
devices.<id>.scanner_id |
Must match Settings → Digital Twin |
devices.<id>.allowed_actuators |
Actuator id → allowed operations |
Example: sidecar/dtam/src/dtam/communication/devices.example.json. Procedure and client scripts: Device link. Board scripts install pip install adelpha and from adelpha import telemetry, feedback.
MRI working directory¶
The Imaging Console stores exams under MRI4ALL_BASE:
| Platform | Default |
|---|---|
| macOS desktop | ~/Library/Application Support/org.adelpha.digital-twin-ui/mri4all |
| Windows desktop | %APPDATA%\org.adelpha.digital-twin-ui\mri4all |
| Linux desktop | ~/.local/share/org.adelpha.digital-twin-ui/mri4all |
Browser / python -m services.api |
adelpha/.mri4all if /opt/mri4all is missing |
Inside that folder:
| Path | Contents |
|---|---|
data/complete/ |
Finished reconstructions (Study Viewer) |
data/archive/ |
Archived exams |
data/acq_queue/, data/acq/ |
Acquisition queue and in-progress |
data/recon_queue/, data/recon/ |
Reconstruction queue and in-progress |
data/failure/ |
Failed scans |
config/ |
mri4all.json, config_acq.json |
logs/ |
acq / recon / ui / api logs |
Settings → Imaging Console → Study data changes this folder. The choice is stored as mri_data.json in the app config directory and applied as MRI4ALL_BASE when the Python runtime starts.
ADELPHA_DATA_DIR still names the Adelpha data root (lock file, default mri4all tree). It does not override a folder chosen in Settings.
MRI console (mri4all.json)¶
Under MRI4ALL_BASE/config/ (default <app-data>/mri4all/config/):
| Field | Role |
|---|---|
scanner_ip |
Red Pitaya / MaRCoS host |
hardware_simulation |
"True" / "False" |
debug_mode |
"True" / "False" |
dicom_targets |
Export destinations |
Ping always probes the network. Sequences talk to hardware only when simulation is False. See Imaging Console.
Persisted UI preferences¶
| Key | Purpose |
|---|---|
adelpha.workspacePrefs |
Startup workspace, restore layout, panel width |
adelpha_workspace_id |
Last workspace |
adelpha.consoleTheme |
adelpha, mri4all, porcelain, or glacier |
adelpha.scannerModel |
Active model id (bundled or imported-…) |
adelpha.importedModels |
Catalog of imported CAD (blobs are in IndexedDB adelpha-cad) |
adelpha.devicePreviews |
Optional device pictures |
adelpha-launch-seen |
Skip intro (desktop: localStorage; browser: sessionStorage) |
twin_magnet_cad_view_v2 |
Explode / wireframe / temp map / scale |
twin_view_tool_rail_pos_v2 |
Tool rail position |
twin_adk_model_id |
Agents model (legacy picker) |
twin_face_mask_style / twin_camera_bg_mode |
Camera overlay |
Engineering Studio stores project work in IndexedDB (adelpha-studio, projects store), keyed by project ID. This includes FEM STEP files, setup, and run references; standalone workspace settings/results; and study history. Existing FEM session drafts and magnet-study records are migrated when opened. The project catalog remains in local storage. Closing a project retains it; Delete project removes its saved work. FEM solver artifacts remain in the runtime data directory.
Software version in About and Status comes from src/twin/adelphaVersion.ts. The installer version is src-tauri/tauri.conf.json.
DTAM process env (browser / extra terminals)¶
| Variable | Typical |
|---|---|
DTAM_API_HOST / DTAM_API_PORT |
127.0.0.1 / 8080 |
DTAM_SCANNER_ID |
simulated_scanner |
ADELPHA_DEVICE_CONFIG |
Path to devices.json (otherwise looked up under the config dirs) |
GOOGLE_API_KEY |
Agents API only |
Custom hardware systems¶
In Settings → Digital Twin → Twin setup, choose Define new system. Enter a name, architecture, and nominal field strength in tesla, then select Save and use system. Profiles are saved locally and remain available in the scanner selector. This does not change the viewport's CAD model.
Hardware profiles stay read-only until Physical control is enabled. They can open without connected sensors; the dashboard waits until measured publications arrive. A profile alone does not open a board connection — see Device link. Select Simulated scanner to return to simulated telemetry; environment selection controls configuration overlays, not hardware connectivity.
Switching scanner profiles or environments updates only the Twin session; the console and agents stay running. Restart runtime remains available for recovery and changes that need a full restart.