Running vortex on linux with mise

README.md

Running Vortex on Linux with mise

description

This guide explains how to get Vortex running on Linux using mise for environment and task management.

It assumes you're working with a Node-based build setup and may encounter issues with DuckDB extension downloads. A small monkeypatch is included to prevent silent failures during the extension install step.

This setup keeps everything reproducible and avoids global toolchain drift by pinning versions via mise.

prerequisites

• Linux (tested on Arch, should work elsewhere)
• Node-compatible environment
• mise installed: https://mise.jdx.dev/
• pnpm (managed via mise in this setup)

setup

1. Install tools via mise

mise install

2. Install dependencies

mise run pnpm-install

3. Build the project

mise run pnpm-build

4. Start the app

mise run start

mise setup

[tools]
node = "22"
pnpm = "10.33.0"
python = "3.11"
dotnet = "9"

[tasks.pnpm-install]
description = "Install dependencies"
run = "pnpm install"

[tasks.pnpm-build]
description = "Build the program"
run = "pnpm run build:all"
depends = ["pnpm-install"]

[tasks.start]
description = "Starts the program"
run = "pnpm run start"
depends = ["pnpm-build"]

duckdb monkeypatch

If you run into issues where DuckDB extensions fail to download or the script exits silently, patch the script to properly surface errors.

Edit:

scripts/download-duckdb-extensions.ts

Add this to the very bottom:

main().catch((err: unknown) => {
  console.error(err);
  process.exit(1);
});

Why this matters

Without this, failures during extension downloads can get swallowed, leaving you with partial or broken installs and no clear error output. This ensures failures are visible and CI/dev runs fail correctly.

notes

• This setup avoids relying on system-wide Node/Python/.NET installs.
• If builds fail, check Node version mismatches first — Vortex tooling tends to be sensitive here.
• DuckDB extension downloads are platform-specific (e.g., windows_amd64 vs linux_amd64), so make sure you're not pulling mismatched artifacts.
• Check ~/.config/@vortex/main/vortex.log for any logs

           .-------------------------:                    dir@leonida
          .+=========================.                    -----------
         :++===++==================-       :++-           OS: CachyOS x86_64
        :*++====+++++=============-        .==:           Host: B650 AORUS ELITE AX
       -*+++=====+***++==========:                        Kernel: Linux 6.19.10-1-cachyos
      =*++++========------------:                         Uptime: 1 hour, 28 mins
     =*+++++=====-                     ...                Shell: fish 4.6.0
   .+*+++++=-===:                    .=+++=:              DE: COSMIC 1.0.0
  :++++=====-==:                     -*****+              WM: cosmic-comp (Wayland)
 :++========-=.                      .=+**+.              Cursor: Adwaita
.+==========-.                          .                 Terminal: cosmic-term 1.0.8
 :+++++++====-                                .--==-.     Terminal Font: Noto Sans Mono (14px)
  :++==========.                             :+++++++:    CPU: AMD Ryzen 7 7800X3D (16) @ 5.05 GHz
   .-===========.                            =*****+*+    GPU 1: NVIDIA GeForce RTX 5070 [Discrete]
    .-===========:                           .+*****+:    GPU 2: AMD Raphael [Integrated]
      -=======++++:::::::::::::::::::::::::-:  .---:      Local IP (wlan0): 10.69.1.139/24
       :======++++====+++******************=.             Locale: en_US.UTF-8
        :=====+++==========++++++++++++++*-
         .====++==============++++++++++*-
          .===+==================+++++++:
           .-=======================+++:
             ..........................