Light

Linux launcher inspired by Spotlight and Raycast. Built with Python 3 + GTK 3.

Status: early public MVP / alpha. Expect rough edges.

Security & API keys

Light does not ship with anyone’s OpenAI key. Installing or cloning this repo cannot expose the author’s keys.

• API keys live only on each user’s machine:
  • ~/.config/light/secrets.json (mode 0600), or
  • the OPENAI_API_KEY environment variable
• Keys are never written to configuration.json, the git repo, Preferences UI storage, or usage metrics
• Config dir is kept private (~/.config/light → 0700)
• OpenAI is optional and off by default — without a key, apps/files/actions still work

Do not commit secrets.json, paste keys into issues/PRs, or share screenshots that show a live key.

See SECURITY.md for the short security policy.

MVP features

• Floating search window (GTK 3)
• Installed application search via freedesktop .desktop entries
• File search via fd, find, or Python fallback
• System actions (sleep, reboot, lock, terminal)
• Web search + URL open
• Calculator with safe evaluation
• Arrow keys, Tab, Enter, Escape navigation
• System tray icon
• Wayland-safe compositor shortcut plus optional keyboard fallback
• Streaming OpenAI answers with source citations (your own API key)
• Opt-in local clipboard history and process-isolated extensions

Requirements

sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-3.0 \
  gir1.2-ayatanaappindicator3-0.1 xdg-utils fd-find

On Ubuntu/Debian, fd-find installs the binary as fdfind (already supported).

Run

chmod +x run.sh
./run.sh

Or directly:

python3 -m light

The search window should open immediately. A magnifying-glass icon appears in the system tray.

Harmless warning

This message is safe to ignore:

Gtk-Message: Failed to load module "appmenu-gtk-module"

Global hotkey (Alt+Space)

Do not use pip install keyboard system-wide on Ubuntu 24.04+ — PEP 668 blocks it.

Option A — System keyboard shortcut (recommended)

On GNOME/Ubuntu, install it automatically:

./run.sh install-hotkey

On KDE and other compositors, this prints the exact desktop-native command to bind. The shortcut invokes Light over D-Bus, so it works reliably on Wayland without reading /dev/input.

Option B — Optional pip package in a venv

./run.sh setup-hotkey   # creates .venv and installs keyboard
./run.sh start-venv     # run with built-in global hotkey

Config

On first run, config is copied to:

~/.config/light/configuration.json
~/.config/light/secrets.json      # recommended place for API keys
~/.config/light/actions.json      # optional user actions

File search

Type any filename fragment — including multiple words:

• readme
• budget report
• invoice 2024

Light matches files whose path contains all words (Raycast/Spotlight-style). Results appear under apps/actions; Google stays as a fallback at the bottom.

AI answers are intentional, not automatic for every multi-word query:

• Questions: who is the ceo of google
• Fact lookups: ceo of google, capital of france
• Explicit AI: ? latest openai news

For fact lookups, Light shows the live answer on top, then matching local files, then Google — Raycast-style parallel results, not exclusive modes.

Currency conversion is built in (live market rates, ECB fallback, no API key):

• 1 usd to inr
• 1 usd to rupees
• 100 euros in usd

Enter copies the converted amount. Rates may still differ slightly from Google depending on provider and update timing.

Light can answer questions like Google’s AI Overview using OpenAI Responses API + web_search. This uses your OpenAI account and quota — Light never embeds a shared key.

1. Create a local secrets file (never commit this file):

mkdir -p ~/.config/light
chmod 700 ~/.config/light
cat > ~/.config/light/secrets.json <<'EOF'
{
  "openai_api_key": "sk-your-key-here"
}
EOF
chmod 600 ~/.config/light/secrets.json

Or export once per shell:

export OPENAI_API_KEY="sk-your-key-here"

2. Enable OpenAI in config (~/.config/light/configuration.json):

"openai_enabled": true,
"openai_model": "gpt-4o",
"openai_web_search": true

3. Restart Light:

./run.sh stop
./run.sh

Then ask: who is the ceo of whatsapp global

Flow: OpenAI web search → short answer under the bar → Wikipedia only if OpenAI is off/unavailable.

Clipboard history

Clipboard history is local-only and disabled by default. Enable it in ~/.config/light/configuration.json:

"clipboard_history_enabled": true,
"clipboard_history_limit": 50

Type clipboard or clipboard <filter> in Light. Entries are stored with mode 0600 in ~/.local/share/light/clipboard_history.json.

Extensions

Put extensions in ~/.local/share/light/extensions/<id>/manifest.json:

{
  "id": "example",
  "name": "Example",
  "prefix": "ex",
  "description": "Run an external extension",
  "command": ["/absolute/path/to/extension"]
}

Typing ex hello launches the command with hello as its final argument and in the LIGHT_QUERY environment variable. Commands are arrays and never run through a shell.

Preferences

Open Tray → Preferences to configure:

• Theme: Raycast Dark, Spotlight Light, or Dracula
• Keyboard hints under results
• OpenAI live answers and web search
• Clipboard history
• Privacy-safe local metrics
• Search paths
• File index status and refresh guidance

Optional fast file index

Recommended for other users too, but not required:

sudo apt install plocate
sudo updatedb

Light auto-detects plocate/locate and falls back to live fdfind search.

Test

PYTHONPATH=. python3 -m unittest discover -s tests -t . -v

Packages

./packaging/debian/build-deb.sh 0.1.0
./packaging/flatpak/build-flatpak.sh

The Debian artifact is written to dist/. Flatpak requires flatpak-builder and the GNOME 48 runtime/SDK.

Validation metrics

Privacy-safe local counters are disabled by default. Set "usage_metrics_enabled": true, then run ./run.sh metrics. Queries, paths, clipboard contents, answers, and API keys are never recorded.

See VALIDATION.md for the real-user validation workflow before paid features.

Project layout

Area	Path
App entry	light/app.py
Launcher UI	light/ui/launcher_window.py
Themes	light/ui/theme.py
Search engine	light/search/search.py
Config	light/configuration/configuration.py
Packaging	packaging/

Known MVP limits

• Wayland layer-shell is used automatically when gir1.2-gtk-layer-shell-0.1 is installed; otherwise Light falls back to a regular always-on-top GTK window
• Automatic Wayland shortcut installation currently targets GNOME; other compositors use the command printed by ./run.sh install-hotkey
• File search without fd/find/plocate is slower on large home folders
• Flatpak build requires flatpak-builder and the GNOME 48 runtime locally
• Power actions may need polkit permissions
• OpenAI web search uses your API quota (Responses API + web_search tool)

Acknowledgments

Light exists because of Snap by techrisdev — an open-source macOS launcher that showed how a clean search-first architecture can feel fast and thoughtful.

This Linux project is a new implementation (Python + GTK), not a line-for-line port, but it was openly inspired by Snap’s structure and product ideas: search providers, actions, configuration, and the overall launcher workflow.

Thank you, techrisdev, for releasing Snap under the GPL and sharing that work with the community.

License

Copyright (C) 2026 Koustav Ganguly (KOUSTAV2409).

Light is free software under the GNU General Public License v3 (or later). See LICENSE for the full terms.