7.0 KiB

Raw Blame History

Verstak

Verstak is a local-first workspace for files, notes, browser captures, activity and work-journal entries. This repository is the desktop application: the Go/Wails host and UI shell that loads plugins from a plugins/ directory next to its executable.

Alpha software. Use a disposable vault while evaluating it. APIs, storage formats and packaging can change before the first stable release.

Components

The public alpha is split into small repositories. Keep their main branches in the same release line when building from source.

Component	Repository	What it is for
Desktop	mirivlad/verstak	This application: vault UI, local host and plugin runtime.
Official plugins	mirivlad/verstak-official-plugins	Files, Notes, Browser Inbox, Activity, Journal, Sync, Todo and other first-party plugins.
Browser extension	mirivlad/verstak-browser-extension	Manual browser captures and opt-in domain-time activity.
Sync server	mirivlad/verstak-sync-server	Optional self-hosted synchronization between devices.
Plugin SDK	mirivlad/verstak-sdk	TypeScript API, JSON schemas and contract tests for plugin authors.
Architecture documentation	mirivlad/verstak-docs	Product, platform and plugin-system design documents.

No server account or browser extension is needed for a local desktop vault.

Build the desktop and official plugins

The current release scripts target Linux. Install Go 1.24+, Node.js 20+ with npm, Python 3, the Wails v2 build prerequisites, and your distribution's WebKitGTK development package.

Clone the repositories as siblings. The directory names below are intentional: the desktop helper finds the official-plugin checkout at ../verstak-official-plugins.

verstak-workspace/
├── verstak/
├── verstak-sdk/
├── verstak-official-plugins/
└── verstak-browser-extension/   # optional for browser integration

git clone https://github.com/mirivlad/verstak.git verstak
git clone https://github.com/mirivlad/verstak-sdk.git verstak-sdk
git clone https://github.com/mirivlad/verstak-official-plugins.git verstak-official-plugins
git clone https://github.com/mirivlad/verstak-browser-extension.git verstak-browser-extension

cd verstak-sdk && ./scripts/build.sh
cd ../verstak-official-plugins && ./scripts/build.sh
cd ../verstak
./scripts/install-dev-plugins.sh
./scripts/build.sh

install-dev-plugins.sh copies the packages from ../verstak-official-plugins/dist/ into this repository's plugins/ directory. build.sh then copies them to build/bin/plugins/, beside the desktop executable:

./build/bin/verstak-desktop

For a manually assembled installation, place each unpacked plugin directory directly in plugins/ beside verstak-desktop; for example, plugins/browser-inbox/plugin.json. Do not put the release archive itself in that directory. The desktop release archive already includes its matching plugins/ directory.

Start with --debug to show internal plugin-provider identifiers and write diagnostic logs:

./build/bin/verstak-desktop --debug

First local vault

Launch the desktop application and choose or create a writable vault folder. Verstak stores its local metadata in that vault; do not point it at a read-only directory.
Create a Дело (workspace) in the Files plugin before assigning captures or activity to it.
Open Notes, Files, Activity and Journal as needed. Activity candidates are only suggestions: a Journal entry and a new Дело are always created by the user.

Browser extension

The extension is optional. Build it locally with npm ci && npm test && npm run build in verstak-browser-extension/, then load dist/chromium as an unpacked Chromium extension or dist/firefox temporarily in Firefox. A signed Firefox XPI is available from the extension's GitHub Releases.

To connect it to the desktop application:

Ensure the browser-inbox plugin is installed and open its settings in Verstak.
Copy the displayed Receiver URL and Pairing Token.
Paste both values into the extension's settings and save.
Use a manual Send Page, selection, link or file action to create a Browser Inbox capture.

Passive domain activity is disabled by default. When the user explicitly turns it on, the extension sends only bounded time totals by normalized domain. It does not send URLs, page titles, page contents, keystrokes, navigation history or inactive-tab time. The extension settings provide a domain exclusion list.

Optional sync server

The sync server is self-hosted and is not required for local use. Build and start a development instance from a sibling checkout:

git clone https://github.com/mirivlad/verstak-sync-server.git verstak-sync-server
cd verstak-sync-server
./scripts/build.sh
./build/bin/verstak-sync-server --port 47732 --data ./server-data \
  --admin-user admin --admin-pass 'choose-a-strong-password'

For a second device or a production host, follow the deployment, HTTPS and backup guidance in the sync server README. In the desktop application, open the Sync plugin, enter the server URL and user credentials, test the connection, then select Connect. Each vault is paired separately.

Release artifacts

Maintainers can produce a self-contained Linux desktop archive after the SDK and official plugins have been built:

cd verstak
./scripts/release.sh v0.1.0-alpha.1

It writes release/verstak-desktop-linux-amd64-<version>.tar.gz and a matching SHA256SUMS file. Unpack the archive and run the included executable; its matching plugins are already in the archive. The browser extension, SDK, official plugins and sync server have their own build or release instructions in their repositories.

Publish a GitHub Release

After checking the local archive, publish the same assets to GitHub:

./scripts/publish-github-release.sh v0.1.0-alpha.1

The command requires an authenticated gh CLI, a clean local main equal to origin/main, and the sibling official-plugins checkout. It runs the local release script, creates an annotated Git tag when needed, pushes that tag through origin, then creates or updates the GitHub Release with the archive and SHA256SUMS. In this checkout origin also pushes the tag to the configured mirror; other maintainers can add a second push URL if they use a mirror too. Publish the compatible official-plugins release before publishing the desktop archive that embeds those plugins.

7.0 KiB Raw Blame History