Omahub
← All plugins
P

Thread

by Pixygon

Open a room on the Thread from your bar — serve a 3D world off your own machine, watch who walks in, and publish it to a domain you own.

GitHub

Security review

Review recommended · 2 findings

Deterministic scan — not a security guarantee

Low
Risk level
Low
Analyzed commit
8f23c95
Scanned
1 month ago

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

  • Docs external_hosts README.md:74

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

    git clone https://github.com/Pixygon/omarchy-thread ~/.config/omarchy/plugins/io.pixygon.thread
  • Docs external_hosts TESTING.md:31

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

    git clone https://github.com/Pixygon/omarchy-thread && cd omarchy-thread

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
8f23c95
Reviewed
1 month ago

The plugin is a bar widget that serves a 3D room over HTTP and connects to a presence relay. The deterministic scan flagged external hosts in README/TESTING.md, but those are documentation-only install examples. The actual code (Rust helper, QML, install.sh) is transparent, builds from source, touches only user-owned directories, and clearly documents its network behavior and file writes. No obfuscation, hidden persistence, or destructive actions were found.

  • The helper opens an HTTP listener on 0.0.0.0 (port 7777+) while a room is open, which is documented and only active during serving.
  • The plugin connects to a third-party relay (wss://relay.pixygon.io) by default, but this is configurable and clearly stated.
  • The install.sh script builds the helper with cargo, which fetches dependencies from crates.io; this is standard and not a security issue.
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/Pixygon/omarchy-thread --enable
Desktop #bar #quickshell #launcher

Thread — a room on your bar

helper

Open a 3D room, served off your own machine, and see who walks into it from the Omarchy bar.

◈ 2

That is two people standing in a place you are hosting. Click the doorway to open a room, copy its address, and paste it to somebody. They walk in. Nobody signed up for anything, and nothing you made left your disk.

What it actually is

The Thread is an open spatial medium: addressable 3D worlds that link to one another the way pages do. A world is a world.json file. A host publishes it at /.well-known/thread/world.json. Any conformant browser can walk in. That is the whole protocol.

This plugin makes your desktop one of those hosts.

  • A room is a directory. ~/Worlds/monday-standup/world.json — a floor, a ring of pillars, a table, four places to stand. Copy it to a USB stick if you like; it is yours, meshes and all. If you happen to have the Thread CLI installed, rooms are designed by its level creator instead — real columns and arches, meshed onto your own disk under models/ and referenced by relative path, so the room owes nothing to anyone's CDN. If you don't have it, the built-in room is used and nothing about the plugin changes. It is an upgrade, never a dependency.
  • Serving it is one command. The helper serves the manifest with the content type and CORS header the spec requires, on your LAN address.
  • The bar watches the room, without entering it. It observes the presence relay: a roster and join/leave events, no body, no pose. Your bar never appears inside your world as a phantom. (That mode was added to the reference relay and the wire spec for this plugin — see presence-wire-v0.1.)
  • If you own a domain, it becomes a real address on the internet. omarchy-thread publish you.com stages the three files; verify then checks the live host exactly the way a browser would and tells you the truth.

Try it in thirty seconds

omarchy-thread new "Monday Standup"   # a room of your own
omarchy-thread open                   # serve it, and step inside
omarchy-thread invite                 # thread://192.168.1.20:7777 — paste this to someone

Anyone on your network opens that address in a Thread browser and is standing in the room with you. For people who aren't on your network, put it on a domain:

omarchy-thread publish you.com
rsync -av ~/Worlds/monday-standup/.publish/ you@you.com:/var/www/you.com/.well-known/thread/
omarchy-thread verify you.com
#  ✓ reachable  ✓ CORS  ✓ content-type  ✓ a conformant thread/0.1 world
#  ◈ thread://you.com is live on the Thread.

Install

Through Omarchy's own plugin manager:

omarchy plugin add https://github.com/Pixygon/omarchy-thread

Or by hand — same result:

git clone https://github.com/Pixygon/omarchy-thread ~/.config/omarchy/plugins/io.pixygon.thread

Then add the Thread widget to your bar in Omarchy's bar settings. The plugin reloads itself on save, like every Omarchy plugin.

The helper (omarchy-thread), which does the serving and the watching — built from source, nothing downloaded:

cd ~/.config/omarchy/plugins/io.pixygon.thread
./install.sh          # cargo-builds the helper into ~/.local/bin

or the same two commands it runs:

cd ~/.config/omarchy/plugins/io.pixygon.thread/helper
cargo build --release
install -Dm755 target/release/omarchy-thread ~/.local/bin/omarchy-thread

It is ~700 lines of Rust with four dependencies, all from crates.io. Read it before you run it; it is short on purpose.

The room assumes a builtin mesh is one unit tall and centred — true in the reference browser from Infinite v0.111.0 onward. On an older build the pillars render at double height and half-sunk, which is a browser to update rather than a world to edit.

A browser to walk in with — Infinite is the reference one. The plugin works without it (it will still serve rooms and show you who is inside), it just can't open the door for you.

What it needs, and what it touches

Documented plainly, because you should know before installing anything:
Binaries it runs omarchy-thread (this repo), wl-copy (copying the address), infinite (only if installed, to open a room), curl (only in verify)
Network in An HTTP listener on port 7777+ bound to 0.0.0.0, serving only the room directory, while a room is open. Nothing listens when no room is open.
Network out One WebSocket to the relay your room's manifest names — rooms this plugin creates name wss://relay.pixygon.io. Delete presence.relays from the world and nothing connects; OMARCHY_THREAD_RELAY is an explicit override for pointing at your own. The manifest is the switch, and the code honours it.
Files it writes ~/Worlds/ (your rooms) and ~/.local/state/omarchy-thread/state.json (what the bar reads)
Privileges None. No root, no polkit, no system config, no pacman repo, no autostart.
Accounts None required. The relay accepts anonymous travelers; a Passport is optional and only makes you recognisable instead of "traveler 7".

Removing it

Everything it installed, undone:

omarchy plugin remove io.pixygon.thread     # or: rm -rf ~/.config/omarchy/plugins/io.pixygon.thread
rm ~/.local/bin/omarchy-thread              # the helper
rm -rf ~/.local/state/omarchy-thread        # its state

Your rooms are yours and live in ~/Worlds — removing the plugin does not touch them. Delete that directory too if you want nothing left. If you installed the thread:// link handler, omarchy-thread handler remove undoes it before you delete the binary.

Identity, and thread:// links

The plugin is not a renderer — Infinite is the browser, the way Firefox is for the web. What the plugin does is make this desktop a first-class citizen of the Thread:

omarchy-thread handler install   # thread:// links open a world, anywhere on the desktop
omarchy-thread passport status   # who you are, if you want to be anyone

Anonymous is the default and always works — the relay takes travelers with no identity at all. A Passport is the portable "you" (a name, an avatar, and consent) that makes you recognisable across worlds instead of "traveler 7". If you have one, omarchy-thread passport set <token> writes it to ~/.config/infinite/passport.token — the same file the browser already reads, so signing in once signs you in everywhere. passport clear makes you a stranger again.

handler install is the only thing here that touches your desktop's settings (the x-scheme-handler/thread default), it is never done for you, and handler remove undoes it.

Configuration

Variable Default
OMARCHY_THREAD_ROOMS ~/Worlds where your rooms live
OMARCHY_THREAD_PORT 7777 first port tried when serving
OMARCHY_THREAD_RELAY wss://relay.pixygon.io the relay the bar observes
OMARCHY_THREAD_NAME $USER the name co-travelers see
OMARCHY_THREAD_FIGURE hall which figure the level creator builds, when present
OMARCHY_THREAD_NO_CLI unset set it to always use the built-in room
OMARCHY_THREAD_STORE unset set it to source models from the online store instead of meshing them locally

Keys, while the panel is open

o step inside · c copy the address · n new room · x close the room

Middle-clicking the bar glyph walks straight in.

The helper

omarchy-thread new <name>            make a room you own
omarchy-thread rooms                 list your rooms
omarchy-thread validate [room|file]  check a world: conformance, presence tier, missing meshes
omarchy-thread open [room]           serve it and step inside
omarchy-thread invite [room]         the address to hand someone
omarchy-thread status                one line of JSON — what the bar reads
omarchy-thread publish <host> [room] stage the room for a domain you own
omarchy-thread verify <host>         check a live host the way a browser does
omarchy-thread stop                  close the room
omarchy-thread doctor                what's installed, what's reachable

validate refuses a room that names meshes which aren't beside it, and publish won't stage one — a manifest missing its assets is still valid JSON, so the failure is otherwise silent and permanent: the room simply loads with holes in it, every time. (Conformance clause C8.)

verify is not Pixygon-specific and has no allegiance: point it at anybody's domain and it will tell you whether they are conformant.

Honest limits

  • v0.1. The room template is one room. Editing a world means editing JSON (or using the Thread CLI's authoring tools) — a visual editor is being built, and is not here yet.
  • Your LAN, or your domain. There is no tunnel and no hosted fallback: if the people you want to invite are not on your network, you need a domain (or a tunnel of your own, e.g. Tailscale or cloudflared). That is a deliberate omission — this plugin does not want to be a service you depend on.
  • Voice is declared, not implemented here. The manifest advertises it; the browser does the talking.
  • The relay is a default, not a requirement. Anyone can run one; the wire protocol is specified and the reference implementation is open.

Licence

MIT. The Thread specification lives at Pixygon/thread-spec and is independent of this plugin — the format, the resolution rule and the presence wire are the standard, not a product.