A native Linux desktop companion for the CANFAR Science Portal, built with Rust, GTK 4, and libadwaita.
Project page, guides and downloads for every platform: verbinal.com.
This is the Linux member of the Verbinal family.
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.
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.
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).
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.
Find an image by package — search 368 container images by what is installed in them, faceted by OS family and version.
Archive search — the CADC observation search: four constraint columns, the faceted data train, an ADQL editor, and a recent-searches rail.
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.
- GTK 4.12+
- libadwaita 1.4+
- A Secret Service provider (GNOME Keyring, KDE Wallet, or similar)
- A CANFAR account
-
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 cfitsiocfitsio backs the FITS and cube viewers and the post-download shape check. It is required by default;
cargo build --no-default-featuresbuilds without it, at the cost of not being able to open any FITS file.
# Debug build
cargo build
# Release build
cargo build --release
# Run
cargo run --releaseThe release binary will be at target/release/verbinal.
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 verbinalThe 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.zstDownload the latest .deb from Releases, then:
sudo apt install ./verbinal_*_amd64.debThe 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 verbinalUpdates 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-buildcargo test# 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 fmtsrc/
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
- GTK 4 + libadwaita for the UI layer
- Tokio multi-threaded runtime for async HTTP, bridged to GTK's GLib main loop via
oneshotchannels - Reqwest with Rustls for HTTPS API calls
- Rc/RefCell ownership model for GTK widgets;
Arcfor cross-thread shared state - Clean separation: Models -> Services -> UI
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 |
GNU Affero General Public License v3.0
Copyright (C) 2025 Serhii Zautkin
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.
See CONTRIBUTING.md.




