Install | Pick a provider | Web search | First run | Shortcuts | Docs

find my contract folder what does this song mean? list files in ~/Documents close spotify and open the terminal

Talk to it the way you'd talk to someone standing next to your keyboard. No flags, no man pages, nothing to memorize.

So, what is this thing

Say hi to Lumina, the face behind the prompt. She's not an actual chat window, she's just here to give the project a personality instead of another generic terminal icon.

DeskLumina sits on your desktop and waits for you to type. Yeah sure, clicking an icon in Plank is faster for opening Spotify, nobody's arguing that. But typing wins the second the task isn't one click away, find that PDF I downloaded last week, close everything except the terminal, what's eating my RAM right now. No dock icon for that. No keyboard shortcut you'll ever remember for that.

Say it in plain language, it figures out the intent, picks the right tool, and runs it.

It doesn't ship its own model. Pick a provider, Groq, OpenAI, Anthropic, and a few others, and DeskLumina borrows its brain from there. Most have a free or near-free tier, use it.

Local model support is on the roadmap. For now, every request travels to whichever provider you pick.

Bring your own brain, literally. Switch providers without touching a single line of code, one .env edit and DeskLumina answers to a different brain. Groq for speed, Claude for a model that double checks itself, Gemini for the free tier, pick whichever fits the job that day.

Before you touch the keyboard

If you've never dealt with an "API key" before, here's the short version.

Think of a provider, Groq, OpenAI, Anthropic, whichever one, as a phone company, and an API key as your SIM card. It's what lets your copy of DeskLumina call up their AI and get an answer back. No key, no line to call on. Each provider hands out its own key, usually for free to start, and you paste that key into one settings file so DeskLumina knows who to dial.

You only need one key to get going. The rest of this README shows you exactly where to get it, whichever provider you land on.

Note

An API key looks like a long jumble of letters and numbers, something like sk-abc123.... Treat it like a password. Never post it publicly, never commit it to GitHub. If one ever leaks, go back to that provider's dashboard and revoke it, then generate a new one.

Get it running

Got Rofi? That's the screen you'll actually be staring at [MANDATORY]

Let's be clear about what Rofi actually is here: it's not a dependency you can shrug off, it's the entire UI. Every prompt, every panel, every menu you'll ever see is Rofi rendering on top of your keystroke. No Rofi, no DeskLumina.

Needs Rofi 1.7+ at minimum, older builds technically launch but render like garbage. Latest stable is 2.0.0 (Wayland support now ships built-in, no separate fork needed anymore). Check what you've got:

rofi -v

Below 1.7, or nothing printed? Install it:

Arch / Manjaro

sudo pacman -S rofi

Debian / Ubuntu

sudo apt install rofi

NOTE: Debian/Ubuntu repos ship old builds. If rofi -v still comes back under 1.7 after this, pull a newer one straight from davatorium/rofi releases.

Fedora

sudo dnf install rofi

openSUSE

sudo zypper install rofi

NOTE: Running Wayland? As of Rofi 2.0.0, Wayland support is built in natively, no extra package needed. If your distro repo still hands you something older than 2.0.0 without Wayland, build from source via meson, see davatorium/rofi for instructions.

Have you installed Bun? [MANDATORY]

DeskLumina runs on Bun, not Node, that's the runtime actually executing the code once everything's cloned. Type bun --version in a terminal, a version number means you're already set, skip straight to step 1.

Nothing printed? One line installs it:

curl -fsSL https://bun.sh/install | bash

Close the terminal and reopen it, or run source ~/.bashrc (~/.zshrc if the shell is zsh), so the bun command gets picked up.

NOTE: Not sure which shell is running? echo $SHELL will tell you.

A few system packages too

Bun runs the code, but a handful of system packages do the actual work once DeskLumina asks for it:

Package	What it's for	Required?
rofi	The entire UI, every panel, prompt, and menu	✅ Yes
mpd + mpc	Powers the "play a song" command	✅ Yes, if you want music control
clipcatctl	Clipboard management for agent capabilites	✅ Yes, if you want clipboard capabilites

Note: clipcatctl ships from the clipcat project, not rofi/mpd. It's only in Arch's official repos, everyone else installs it separately, see below.

Arch / Manjaro

sudo pacman -S rofi mpd mpc clipcat

Debian / Ubuntu

sudo apt install rofi mpd mpc

Fedora

sudo dnf install rofi mpd mpc

After installing mpd, make sure it's actually running:

systemctl --user enable --now mpd

Installing clipcatctl (Debian / Ubuntu / Fedora)

`clipcat` (the package that provides `clipcatctl`) isn't in the Debian, Ubuntu, or Fedora repos, Arch is the only one that has it official. Everywhere else, grab a prebuilt release instead of building from source.

Debian / Ubuntu (.deb):

export CLIPCAT_VERSION=$(basename "$(curl -s -w '%{redirect_url}' https://github.com/xrelkd/clipcat/releases/latest)")
curl -sLO "https://github.com/xrelkd/clipcat/releases/download/${CLIPCAT_VERSION}/clipcat_${CLIPCAT_VERSION#v}_amd64.deb"
sudo dpkg -i "clipcat_${CLIPCAT_VERSION#v}_amd64.deb"

Fedora (.rpm):

export CLIPCAT_VERSION=$(basename "$(curl -s -w '%{redirect_url}' https://github.com/xrelkd/clipcat/releases/latest)")
curl -sLO "https://github.com/xrelkd/clipcat/releases/download/${CLIPCAT_VERSION}/clipcat-${CLIPCAT_VERSION#v}-1.el7.x86_64.rpm"
sudo dnf install --assumeyes "clipcat-${CLIPCAT_VERSION#v}-1.el7.x86_64.rpm"

Any distro, from source (needs cargo/Rust):

git clone --branch=main https://github.com/xrelkd/clipcat.git
cd clipcat
cargo install --path clipcatctl

Tip: don't need the clipcat-menu picker, just the CLI DeskLumina talks to? cargo install --path clipcatctl alone is enough, skip the other two binaries.

1. Clone it into the right spot

git clone https://github.com/Rafacuy/desklumina.git ~/.config/desklumina
cd ~/.config/desklumina

(no git yet? most Linux distros already ship it, otherwise your package manager has it)

Warning

DeskLumina has to live at ~/.config/desklumina. Clone it anywhere else and it won't find its own files.

2. Install the dependencies

bun install

3. Tell it which brain to use

cp .env.example .env

Open .env in any text editor, VS Code, gedit, nano, whatever you have, and fill in one provider key, then set the model:

GROQ_API_KEY=gsk_your_actual_key_here
DESKLUMINA_MODEL=groq:llama-3.3-70b-versatile

That's the default and it works well straight out of the box. Every provider and every model option lives in Configuration, but you don't need that yet, the two lines above are enough to start. If you'd rather pick a different provider first, jump to Pick a brain below, there's a short walkthrough for each one.

Want a faster launch every time?

Compile once, then run the production build instead of rebuilding on every start:

bun run build
bun run start:prod

Pick a brain

DeskLumina doesn't care which provider you pick, as long as one _API_KEY in your .env is filled in and unused providers are simply left blank. Below are the six currently supported. Open whichever interests you, each has a short video and a direct link to grab the key.

Groq, fast responses, generous free tier

Groq runs open models (Llama, Mixtral, and others) on hardware built specifically for speed. Answers come back quickly, and the free tier covers daily use comfortably.

• Get a key: console.groq.com/keys
• Official docs: console.groq.com/docs
• Set in .env:

  GROQ_API_KEY=
  DESKLUMINA_MODEL=groq:llama-3.3-70b-versatile

_{Credit: @error-slayer}

OpenRouter, one key, dozens of models from every lab

OpenRouter sits in front of most other providers, so a single key can reach models from OpenAI, Anthropic, Meta, and more. Useful if you want to try different models without collecting five separate keys. Some models listed there cost nothing at all.

• Get a key: openrouter.ai/keys
• Official docs: openrouter.ai/docs
• Set in .env:

  OPENROUTER_API_KEY=
  DESKLUMINA_MODEL=openrouter:openrouter/free

(swap in any model slug from openrouter.ai/models)

_{Credit: @Thrivemedia0}

OpenAI, the GPT family, billed from the first token

OpenAI's API has no ongoing free tier, you'll need to add a small amount of billing credit before it answers anything. Worth it if you already pay for ChatGPT and want the same models running on your desktop.

• Get a key: platform.openai.com/api-keys
• Official docs: platform.openai.com/docs
• Set in .env:

  OPENAI_API_KEY=
  DESKLUMINA_MODEL=openai:gpt-5.4-mini

_{Credit: @unitedtoptech6288}

Anthropic, Claude, cautious by design, no free API tier

Anthropic makes Claude. Like OpenAI, there's no standing free tier for the API, new accounts usually get a small starter credit and then it becomes pay as you go. Worth picking if you want a model that tends to double check before running anything risky on your machine.

• Get a key: console.anthropic.com/settings/keys
• Official docs: docs.claude.com
• Set in .env:

  ANTHROPIC_API_KEY=
  DESKLUMINA_MODEL=anthropic:claude-haiku-4-5

_{Credit: @go9x}

Google AI Studio, Gemini models, a real free tier

Google AI Studio is where you generate a key for Gemini. There's a genuine free tier, smaller and rate limited, but enough to try things out without adding a card. One thing that trips people up: the environment variable is GEMINI_API_KEY, but the model prefix in DESKLUMINA_MODEL is also gemini, not google.

• Get a key: aistudio.google.com/app/apikey
• Official docs: ai.google.dev/gemini-api/docs
• Set in .env:

  GEMINI_API_KEY=
  DESKLUMINA_MODEL=gemini:gemini-3.5-flash

_{Credit: @ShaxFinds}

Hugging Face, open models, a small free allowance

Hugging Face hosts inference for a huge range of open weight models. A free account comes with a small amount of monthly credit, enough for light use. A solid option if you want to try a specific open model by name rather than a general purpose assistant.

• Get a token: huggingface.co/settings/tokens
• Official docs: huggingface.co/docs/api-inference
• Set in .env:

  HF_API_KEY=
  DESKLUMINA_MODEL=huggingface:meta-llama/Llama-3.3-70B-Instruct

_{Credit: @IT_explainer}

One key is all you need to run DeskLumina. If you'd rather have backups ready in case the first provider runs dry or goes down, list a few more in DESKLUMINA_FALLBACKS, comma separated, tried in order:

DESKLUMINA_FALLBACKS=groq:llama-3.3-70b-versatile,openrouter/free,anthropic:claude-haiku-4-5,openai:gpt-5.4-mini,huggingface:meta-llama/Llama-3.3-70B-Instruct,gemini:gemini-3.5-flash

There's also DESKLUMINA_EMBED_MODEL, optional, and only relevant if you're using semantic search or RAG style features. Same provider:model format, for example openai:text-embedding-3-small.

Give it eyes on the web

Web search is a separate feature and needs its own key. DeskLumina doesn't ship with built in search access, providers charge per query, and giving every install a shared key would get expensive and rate limited within a day. So this part is bring your own.

You can set more than one search key at once. DeskLumina falls back to the next one if a request fails or a limit is hit.

Tavily, built for AI agents, has a free tier

• Get a key: tavily.com
• Docs: docs.tavily.com
• Set in .env: TAVILY_API_KEY=

Serper, fast Google search results, has a free tier

• Get a key: serper.dev
• Docs: serper.dev
• Set in .env: SERPER_API_KEY=

SerpApi, wide search engine coverage, has a free tier

• Get a key: serpapi.com
• Docs: serpapi.com/search-api
• Set in .env: SERPAPI_API_KEY=

SearXNG, self hosted, no key needed if it's your own instance

Already running a private SearXNG instance? Point DeskLumina at it directly instead of paying for a commercial key:

SEARXNG_BASE_URL=https://searx.example.com
SEARXNG_AUTH_HEADER_NAME=
SEARXNG_AUTH_HEADER_VALUE=

The auth header lines only matter if your instance sits behind one.

• Docs: docs.searxng.org

Two more settings round this out, both optional:

# which provider to try first. auto just picks the first one you've configured
DESKLUMINA_WEB_SEARCH_PROVIDER=auto

# how long to wait before giving up, in milliseconds. 2000-20000 is reasonable
DESKLUMINA_WEB_SEARCH_TIMEOUT_MS=8000

Important

Skip this section entirely and DeskLumina still runs fine, it just can't search the web. Any request that needs it will fail with a clear message instead of hanging forever.

Say hello

bun run start

Then just type. A session looks something like this:

Prefer a darker palette? DeskLumina ships a dark mode too:

Here you go !

Important

You can activate dark mode in Settings.

Warning

A safety layer sits between DeskLumina and your shell. Anything destructive, rm -rf and its relatives, gets intercepted and asks for confirmation first. Nothing dangerous runs silently.

Note

DeskLumina ships UI and TTS for multiple languages. The supported list is kept in one place: Configuration → Supported languages.

Bind it to a key

Typing bun run start every single time gets old fast. Bind the launch to a shortcut instead, so the Rofi input bar pops up on demand, the same way rofi -show drun does.

Tip

Compile the production binary once (bun run build), then point every shortcut at start:prod. Skipping the on-the-fly TypeScript transpile shaves off real time, and it's noticeable on hardware this modest.

sxhkd

Add a line to ~/.config/sxhkd/sxhkdrc:

super + l
    cd ~/.config/desklumina && $HOME/.bun/bin/bun run start:prod

Reload with pkill -USR1 sxhkd, or just restart the session. The cd matters, DeskLumina expects to be launched from its own folder, and $HOME/.bun/bin/bun sidesteps the fact that sxhkd doesn't read your shell's PATH.

XFCE keyboard shortcuts

1. Open Settings → Keyboard
2. Switch to the Application Shortcuts tab
3. Click Add and paste in:

bash -c "cd ~/.config/desklumina && $HOME/.bun/bin/bun run start:prod"

Assign it to whatever combo isn't already taken, Super+l is usually free on a stock XFCE install.

i3 / bspwm / other WMs

Same idea everywhere, any WM that reads a config file for keybindings works the same way. Drop this into i3config, bspwmrc, or the equivalent:

bindsym $mod+l exec --no-startup-id "cd ~/.config/desklumina && $HOME/.bun/bin/bun run start:prod"

Swap bindsym and exec for whatever syntax your WM's config expects, the command itself doesn't change.

Note

Haven't compiled yet? start:prod fails silently if bun run build was never run. Shortcut managers won't show an error either, there's no terminal attached to display one.

Map of the docs

Everything below is written for humans, not linted for a docs generator. Open the page that matches what's actually stuck, not the whole stack at once.

Learn how it works

• Usage Guide walks through everyday commands.
• Architecture covers how a request travels from your keyboard to a finished action.

Configure it your way

• Configuration lists every environment variable that exists.
• Tools Reference documents everything DeskLumina can actually do.
• Quick Reference is the cheat sheet version of both.

Build on top of it

• Development for setting up a local dev environment.
• API Reference if you're extending DeskLumina itself.
• Roadmap for what's planned next.

When something breaks

• Troubleshooting for the errors people actually hit.
• Security for how keys, confirmations, and the safety layer work underneath.

MIT License · LICENSE