Skip to content

About

A native Linux desktop client for the CANFAR Science Portal — sessions, VOSpace, CADC archive search, FITS and cube viewers, and 160+ MCP tools so an AI agent can drive it. Rust · GTK 4 · libadwaita.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Verbinal for Linux

A native Linux desktop companion for the CANFAR Science Portal, built with Rust, GTK 4, and libadwaita.

CI Release License: AGPL-3.0

Project page, guides and downloads for every platform: verbinal.com.

This is the Linux member of the Verbinal family.

The same app on other platforms

Verbinal is one application per platform, each written natively for it, sharing the behaviour rather than the code. Where they differ, this repository is the one that leads.

Platform Source Install
Linux (this repo) CanfarDesktopUbuntu — Rust · GTK 4 · libadwaita Latest .deb
Windows CanfarDesktop — C# · WinUI 3 Microsoft Store
macOS canfar-macos — Swift · SwiftUI —
iOS / iPadOS — App Store
Android canfar-android — Kotlin Play (testing)

The service all of them talk to is the CANFAR Science Portal (opencadc/science-portal), operated by the Canadian Astronomy Data Centre.

Related projects

These open-source companions are what two of Verbinal's features actually run on the platform:

  • verbinal-execution — a CANFAR/Skaha contributed-session image that powers Verbinal's AI remote compute (run_code). It is a file-drop watcher that runs agent-supplied Python/bash snippets and writes JSON results back — no shell, no inbound network. Run it in a contributed session to let your AI assistant execute code on the platform on your behalf.
  • inspector-image — a minimal Alpine container image with Anchore syft preinstalled, used as the Skaha/CANFAR inspector that powers Verbinal's image content discovery (probing container images for their Python, R, system, and OS-level packages) — the "Find image by package" dialog above.

Features

Each area is reachable from the Home tiles or the sidebar.

Portal — launch, monitor, renew and delete CANFAR sessions (Notebook, Desktop, CARTA, Contributed, Firefly, Headless), from the image catalogue or a custom registry image with its own credentials. Alongside them: VOSpace home quota, live cluster CPU/GPU/RAM load, batch-job counts, and recent launches you can re-run in a click. Active sessions refresh themselves while any one is pending.

Find an image by package — the catalogue runs to hundreds of container images, and their names do not say what is inside them. Search by installed package instead (Python, R, system, OS), faceted by OS family and version, with inspection run on the platform by inspector-image.

Archive search — CADC observation search across four constraint columns, narrowed by a faceted data train of many thousands of entries, or written directly in ADQL. The editor checks a query against the service's own schema as you type: the offending words are underlined, the fix is named, and Execute greys out rather than spending a round trip on a query that cannot work. Results paginate, sort, filter, hide columns, switch units per column, and export as CSV or TSV.

Research — observations you saved are downloaded whole (preview + FITS) to a local library that then needs no network, with your notes attached and a record of which agent, if any, put them there. The whole library exports as a single citable .zip.

Storage — browse, upload and download VOSpace files.

Notebooks — open and run .ipynb files, with cell output rendered for every MIME type the parser models.

FITS viewer — multi-tab, with WCS, colormaps and stretches, percentile and zscale cut levels, an extension selector, a crosshair reading sky coordinates, saved coordinates, and blink / linked-crosshair / synced-zoom comparison across tabs.

Cube viewer — GPU ray-marched volume rendering with an opacity transfer function, plus a 2D slice view with a channel scrubber and per-voxel spectra.

Marks and figures — draw circles and boxes on an image or a cube, label them, move and resize them, and give each its own colour, weight and thickness. They persist with the file. Export the view, or a region you drag out of it, as a publication figure carrying the region's real sky coordinates, the cut levels and a colorbar — at 1×, 2× or 4×.

Workflows — research protocols as check-off step cards, from built-in templates or your own local copies. The file is the state, so a protocol is something you can commit.

AI agent access — 160+ MCP tools over a local Unix socket, so an assistant can drive the app, read what is on screen, point at part of it and hand back a figure. Writes are proposed and applied rather than silently performed, and the sidebar says when an agent is working. With verbinal-execution in a contributed session, it can run code on the platform on your behalf.

Secure credentials — tokens stored in the system keyring via Secret Service (GNOME Keyring / KDE Wallet).

Screenshots

The Home page: one tile per area of the app, with the signed-in account and the agent's state at the top of the sidebar

Portal — platform load, your storage quota and batch jobs across the top; running sessions with what they are actually using; and the image catalogue, filtered by session type and by project. Launching is one button away rather than a form taking up the page.

The Portal page: platform load, storage quota and batch job counts across the top, two running notebook sessions with their resource use, and the CANFAR image catalogue filtered by session type and project, beside a list of recent launches

Find an image by package — search 368 container images by what is installed in them, faceted by OS family and version.

The find-image-by-package dialog, with OS facets on the left and matching images on the right

Archive search — the CADC observation search: four constraint columns, the faceted data train, an ADQL editor, and a recent-searches rail.

The CADC archive search form

Export a figure — what the FITS viewer hands back: the marks you drew with their labels, the region's real sky coordinates, the cut levels and a colorbar.

An exported figure of a JWST NIRCam image with four labelled marks, sky coordinates, cut levels and a colorbar

Requirements

Runtime

  • GTK 4.12+
  • libadwaita 1.4+
  • A Secret Service provider (GNOME Keyring, KDE Wallet, or similar)
  • A CANFAR account

Build

  • Rust 1.75+ (2021 edition)

  • System development packages:

    # Debian / Ubuntu
    sudo apt install libgtk-4-dev libadwaita-1-dev libcfitsio-dev pkg-config
    
    # Fedora
    sudo dnf install gtk4-devel libadwaita-devel cfitsio-devel
    
    # Arch
    sudo pacman -S gtk4 libadwaita cfitsio
    

    cfitsio backs the FITS and cube viewers and the post-download shape check. It is required by default; cargo build --no-default-features builds without it, at the cost of not being able to open any FITS file.

Building

# Debug build
cargo build

# Release build
cargo build --release

# Run
cargo run --release

The release binary will be at target/release/verbinal.

Installing on Arch / Omarchy

Verbinal has its own pacman repository, so updates arrive with the rest of the system rather than being something to remember.

# Trust the signing key, once
curl -fsSL https://verbinal.com/linux/arch/verbinal.gpg | sudo pacman-key --add -
sudo pacman-key --lsign-key 61FBCBA86674EFAF009D49495AD7FD0C3CCCD519

# Add the repository
sudo tee -a /etc/pacman.conf <<'EOF'

[verbinal]
Server = https://verbinal.com/linux/arch/$arch
EOF

sudo pacman -Sy verbinal

The key is fetched from the site rather than a keyserver, because pacman-key --recv-keys depends on propagation and on port 11371 being open, and a first command that hangs is where people stop. --lsign-key is what makes it trusted locally; without it pacman knows the signature but not whether to believe it. The fingerprint is 61FBCBA86674EFAF009D49495AD7FD0C3CCCD519 — check it against the key you just added with pacman-key --finger 61FBCBA86674EFAF009D49495AD7FD0C3CCCD519.

After that, pacman -Syu upgrades Verbinal along with everything else. On Omarchy it also shows up in omarchy-pkg-install, which is a wrapper around pacman and reads the same configuration.

gst-plugins-good is an optional dependency: it is what plays the agent's sound cues. Without it the app is silent and otherwise unchanged, which is a poor reason to refuse to install.

To install a single version without adding the repository:

sudo pacman -U https://verbinal.com/linux/arch/x86_64/verbinal-1.4.4-1-x86_64.pkg.tar.zst

Installing from .deb

Download the latest .deb from Releases, then:

sudo apt install ./verbinal_*_amd64.deb

The leading ./ is what tells apt this is a local file rather than a package name, and apt pulls in any missing dependencies in the same step — which is why this is preferred over dpkg -i followed by apt-get install -f, which is the same job in two commands with a broken state in between.

Everything it needs is in Ubuntu's own archive: GTK 4, libadwaita, glib and cfitsio. On Ubuntu 24.04 the last two are named libglib2.0-0t64 and libcfitsio10t64 after the 64-bit time_t transition; both carry versioned Provides: for the old names, so the dependencies resolve without anything special. libgtk-4-media-gstreamer is recommended, not required — it is what plays the agent's sound cues, and without it the app is silent and otherwise unchanged.

To remove it:

sudo apt remove verbinal

Updates are manual. There is no APT repository or PPA yet, so apt upgrade will not find new versions — watch Releases (or the project page) and install the new .deb over the old one.

Or build the .deb yourself:

cargo install cargo-deb
cargo build --release
cargo deb --no-build

Running Tests

cargo test

Code Quality

# Lint — the exact command CI runs, on the compiler CI runs it with:
# rust-toolchain.toml pins the version, so rustup uses it for every cargo
# invocation in this tree and a green local run really is a green CI run.
# (It was not, once: CI took the day's stable, 1.98 added a lint, and three
# call sites went red in CI while staying green on a 1.97 desktop.)
# `--all-targets` includes the tests. `dead_code` is NOT suppressed: an unused
# function is usually a feature that was written and never wired up, which is
# how several shipped defects here stayed invisible.
rustup update stable   # CI runs the latest stable; an older local clippy sees fewer lints
cargo clippy --all-targets -- -D warnings

# Format check
cargo fmt -- --check

# Format (apply)
cargo fmt

Project Structure

src/
  main.rs              # Application entry point
  config.rs            # API endpoints and app configuration
  state.rs             # Shared application state (AppServices)
  style.css            # GTK CSS theme overrides
  helpers/             # Utility functions (image parsing)
  models/              # Data structures (Session, Image, etc.)
  services/            # API clients and business logic
  ui/                  # GTK widget components
assets/                # Session type icons

Architecture

  • GTK 4 + libadwaita for the UI layer
  • Tokio multi-threaded runtime for async HTTP, bridged to GTK's GLib main loop via oneshot channels
  • Reqwest with Rustls for HTTPS API calls
  • Rc/RefCell ownership model for GTK widgets; Arc for cross-thread shared state
  • Clean separation: Models -> Services -> UI

API Endpoints

All communication is with CANFAR services over HTTPS. No telemetry, analytics, or third-party calls.

Service Base URL Purpose
Auth ws-cadc.canfar.net/ac Login, token validation, user info
Sessions ws-uv.canfar.net/skaha/v1 Session CRUD, images, context, stats
Storage ws-uv.canfar.net/arc VOSpace quota

License

GNU Affero General Public License v3.0

Copyright (C) 2025 Serhii Zautkin

Privacy

See PRIVACY.md. In short: no data collection, no telemetry, no third-party services. All data stays on your machine or goes directly to CANFAR.

Contributing

See CONTRIBUTING.md.

About

A native Linux desktop client for the CANFAR Science Portal — sessions, VOSpace, CADC archive search, FITS and cube viewers, and 160+ MCP tools so an AI agent can drive it. Rust · GTK 4 · libadwaita.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages