Omahub
← All plugins
J

Llama Swap

by Jared Hatfield

Monitor active Llama Swap requests and load or unload models from the Omarchy bar.

GitHub Homepage

Security review

Review recommended · 1 finding

Deterministic scan — not a security guarantee

Low
Risk level
Low
Analyzed commit
b94d8ab
Scanned
1 month ago

Flagged patterns appear only in documentation files (README / docs) — descriptive examples, not executable code.

  • Docs external_hosts README.md:87

    Downloads or connects to an external HTTP(S) host.

    git clone https://github.com/UnitVectorY-Labs/omarchy-plugin-llama-swap.git

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
b94d8ab
Reviewed
1 month ago

The plugin is a benign bar widget that monitors and controls a user-configured Llama Swap server. It makes HTTP requests to that server, passes an optional API token via stdin (never in argv), and bounds all remote responses. The only deterministic finding is a git clone command in the README, which is documentation only and not part of the executable code.

  • The API token is stored in plain text in the Omarchy config file, but this is disclosed in the README and is typical for such widgets.
  • The plugin makes network requests to a user-specified server; a malicious server could return crafted data, but the helper caps response sizes and record counts, and QML renders strings as plain text.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/UnitVectorY-Labs/omarchy-plugin-llama-swap --enable
Widgets #ai

Llama Swap for Omarchy

An Omarchy Quattro bar plugin for monitoring and controlling a Llama Swap server.

The panel shows active inference requests, lists every configured model in a compact scrolling view, and lets you load or unload multiple models with immediate, optimistic switches.

Requirements

  • Omarchy Quattro with shell plugin support
  • bash, curl, awk, and GNU coreutils (included with Omarchy)
  • A reachable Llama Swap server
  • An optional Llama Swap API key when the server requires authentication

The plugin runs inside Omarchy's long-lived Quickshell process with your user permissions. It does not require elevated privileges, install hooks, or a second Quickshell process.

Install

omarchy plugin add https://github.com/UnitVectorY-Labs/omarchy-plugin-llama-swap.git --enable

The widget is placed in the right bar section by default. Move it with the standard Omarchy command if desired:

omarchy bar move io.github.unitvectory-labs.llama-swap --section right

Configure

Set the Llama Swap base URL:

omarchy bar set io.github.unitvectory-labs.llama-swap url https://llama-swap.example.com

Authentication is optional. When configured, the token is sent as an Authorization: Bearer header. The plugin passes it to the request helper over standard input, so it is never included in process arguments:

omarchy bar set io.github.unitvectory-labs.llama-swap apiToken YOUR_TOKEN

Omarchy persists bar-widget settings in ~/.config/omarchy/shell.json. The API token is therefore stored as plain text and is readable by the local user account. Use a suitably scoped token and do not use this implementation where local plain-text storage is unacceptable.

Remote responses are bounded before they enter Quickshell: model snapshots are limited to 1 MiB, and each event-stream connection is limited to 2 MiB, 512 data records, and 64 KiB per record. Model/request state is capped as a second layer of protection, and server-provided strings are rendered as plain text.

Usage

Click the llama icon to open or close the panel. Press Escape or click outside the panel to close it.

  • Models retain the same name/ID ordering used by Llama Swap's interface.
  • Models appear in a compact scrollable list, consistent with Omarchy's Wi-Fi and Bluetooth panels.
  • Model switches move immediately, and load or unload operations for different models can run independently.
  • Loaded model names appear as compact pills beneath the panel header; additional names collapse into a count.

Connection lifecycle

The plugin is live only while its panel is visible:

  1. Opening the panel fetches a current GET /v1/models snapshot.
  2. It connects to the /api/events server-sent event stream and shows the model, endpoint, and elapsed time for active requests.
  3. Closing the panel terminates the event process and clears transient request state.

There is no periodic polling or persistent event connection while the panel is closed. A user-requested model load or unload is allowed to finish after the panel closes, then performs one replacement model snapshot.

API endpoints

The plugin calls these Llama Swap endpoints:

  • GET /v1/models — list models and load state
  • GET /api/events — follow active requests while the panel is open
  • GET /upstream/:model/ — load a model, matching Llama Swap's own UI
  • POST /api/models/unload/:model — unload a model

Remove

omarchy plugin remove io.github.unitvectory-labs.llama-swap

Removal disables the widget and removes its installed checkout according to Omarchy's standard plugin lifecycle.

Development

Clone the repository, validate the manifest, and lint both QML entry files against the installed Omarchy shell:

git clone https://github.com/UnitVectorY-Labs/omarchy-plugin-llama-swap.git
cd omarchy-plugin-llama-swap
omarchy plugin validate .
qmllint -I "$OMARCHY_PATH/shell" BarWidget.qml Panel.qml

The bounded request helper has a host-independent integration test:

python3 tests/test_request_helper.py

For live development, symlink the checkout under the permanent plugin ID, rescan, and enable it:

ln -s "$PWD" "$HOME/.config/omarchy/plugins/io.github.unitvectory-labs.llama-swap"
omarchy-shell shell rescanPlugins
omarchy plugin enable io.github.unitvectory-labs.llama-swap

Files under ~/.config/omarchy/plugins/ hot-reload when saved. Before publishing a change, test click, Escape, shell summon/hide, disable/re-enable, and a shell restart.

License

MIT