Maryk App Desktop Guide

Overview

Maryk App is the desktop UI for Maryk stores. Use it to inspect models, scan records, edit values, and export/import data.

First launch: unsigned desktop packages

Current macOS and Windows release packages are not code-signed, so your operating system may block the first launch. On macOS, first try to open the app, then go to System Settings → Privacy & Security and select Open Anyway. On Windows, a security warning may appear; continue only after confirming that you downloaded the package from the official Maryk release page.

Prerequisites

• JDK 21+ (the Gradle build uses a Java 21 toolchain).
• Local store or remote HTTP endpoint.
• FoundationDB users: install libfdb_c (see /store/foundationdb/).

Run locally

From repo root:

./gradlew :app:run

First-time workflow

1. Open Stores window.
2. Add a store config (RocksDB / FoundationDB / Remote).
3. Open store.
4. Select model in catalog.
5. Scan/filter/sort records.
6. Open a record.
7. Edit with the form.
8. Save and verify in History tab.

Store types

• RocksDB:
  • Local directory path.
  • Single process lock applies.
• FoundationDB:
  • Directory path.
  • Optional cluster file.
• Remote:
  • HTTP URL to CLI serve endpoint.
  • Optional SSH tunnel.

Saved configs: ~/.maryk/app/stores.conf.

Remote setup (HTTP + optional SSH)

Server side example:

maryk --exec "serve rocksdb --dir /path/to/store --port 8210"

(--connect is not needed for serve in one-shot mode.)

Then in app:

1. Add store type Remote.
2. Set URL (http://host:8210).
3. If needed, enable SSH tunnel and set host/user/port/identity.

Notes:

• Remote transport is HTTP. For direct public access, terminate HTTPS/TLS in a reverse proxy and forward to a loopback-bound Maryk server. SSH tunneling is an alternative for private or administrative access, not the only way to encrypt transport.
• If server binds to loopback (127.0.0.1) on remote host, set URL to that loopback URL and use SSH tunnel.

UI map

• Stores window:
  • Saved store list.
  • Add/edit/remove/open.
• Browser window:
  • Left: model catalog.
  • Center: data/model tabs.
  • Right: record inspector.
  • Top bar: connection info, actions, panel toggles.
  • Operations menu: migration status, metrics, pause, resume, cancel, and refresh.

Data browsing

• Model search with fuzzy match.
• Scan paging.
• Sort by key or index.
• Filters via builder or raw YAML.
• Pin model fields to columns.
• Row actions: open, edit, copy key/data, export, delete.

Record inspector

• Data tab:
  • Structured tree view.
  • Search.
  • Reference navigation and preview.
• Raw tab:
  • YAML.
  • Search/copy.
• History tab:
  • Version timeline.
  • Diff view.

Record editor

The form editor provides:

• Typed inputs with inline validation.
• Support for scalar and complex definitions:
  • List / Set / Map / IncrementingMap.
  • Embedded object/values.
  • MultiType (type select + value editing).
  • Reference, bytes, date/time/datetime, enums, numbers, booleans, strings.

Import / export

• Schema export: JSON, YAML, Proto, Kotlin.
• Data export: row/model/all.
  • In time-travel mode, row exports read the selected version boundary. Row history exports use that boundary directly; otherwise they capture a snapshot when the store supports it.
  • With historical retention and an authoritative snapshot provider, row/model/all history exports and model/all current-state exports capture a point-in-time version before paging. Otherwise the app refuses a point-in-time export.
  • Version-history exports include soft-deleted records and their deletion changes.
  • Without historical retention, current-state export remains available, but concurrent writes can appear across pages.
• Data import:
  • Auto-detect format/scope.
  • Expects Maryk export structures (metadata + versioned changes where applicable).

Shortcuts

• Cmd/Ctrl+R: reload scan.
• Cmd/Ctrl+B: toggle catalog.
• Cmd/Ctrl+I: toggle inspector.
• Esc: close drawer/dialog.
• Arrow/PageUp/PageDown: move selection.
• Enter/Space: open selected record.
• Cmd/Ctrl+click: multi-select.
• Shift+click: range select.

Troubleshooting

• Cannot open RocksDB:
  • Ensure no other process has the DB open.
• FoundationDB connect fails:
  • Check libfdb_c, cluster file.
• Remote connect fails:
  • Verify CLI serve running.
  • Check URL/port/tunnel target.
• Empty scans:
  • Confirm selected model and filter expression.

Local state paths

• Store configs: ~/.maryk/app/stores.conf.
• UI prefs (panel/pins): Java Preferences node io.maryk.app.ui.