Vessel

A small radar. A world of ships.

A marine radar for Omarchy. Discover nearby ships, see where they’re heading, and explore the traffic along your coast.

See nearby AIS-equipped vessels, colored by type, with their names, speed, destinations and recent tracks on a map with coastlines and coastal cities. Vessel follows your Omarchy palette and lives behind a single boat icon in the bar.

Tour with demo traffic, sped up. The screenshots below show real AIS traffic.

Screenshots

Real AIS traffic received from OpenWaters on 27 September 2026, with the detailed OpenFreeMap map of Genoa. These are captured snapshots; vessel positions and timestamps reflect the reports received.

Dark palette

Light palette

Compact panel

Dark	Light

Why I built Vessel

When I’m working by the sea, I often watch boats go by and wonder: What’s that boat called? Where has it been? Where is it heading?

I wanted a widget I could glance at while working, connecting the boats on the horizon to the information they broadcast, and fitting naturally into my Outpost and Haven themes.

Thank you to Wes Grimes, the creator of Omastorm, whose work inspired me to improve Vessel's map and zoom controls.

Install

Requires Omarchy 4 with Quickshell plugin support and Python 3.11+ with venv.

omarchy plugin add https://github.com/simoz/omarchy-vessel.git --enable

Accept the plugin trust prompt and click the boat icon to open the radar, then choose Settings to configure it. The live receiver's Python dependency is installed automatically on first use.

Configure

1. Under LOCATION, search for a CITY and select a result, or choose IP LOCATION or COORDINATES. Focusing the city field selects its text so you can replace it immediately.
2. Under COVERAGE, set the radius (1–200 nautical miles) and distance units: nm, km or mi. Speed is shown in knots (kn).
3. Under AIS CONNECTION, keep OpenWaters selected. No account or key is required. An optional personal token raises the limits. To use AISStream instead, select it, click GET AN API KEY, and paste your AISStream key.
4. Click SAVE & CONNECT. Save and Cancel stay visible while you scroll.

OpenWaters loads recent positions immediately, then streams updates. Positions retain their original timestamps. Anonymous access allows 20 messages/second, two connections per IP and 100 square degrees of coverage; excess messages are thinned. Large radii at high latitudes may require a personal token or a smaller radius.

Use CHANGE to replace a saved credential. An empty key field preserves it. OpenWaters tokens and AISStream keys are stored separately. Preferences and credentials are stored in ~/.config/omarchy-vessel/settings.json (or $XDG_CONFIG_HOME/omarchy-vessel/settings.json), with owner-only file permissions (0600). Keep this file out of public dotfile backups.

OpenWaters availability and limits · AISStream documentation

Use the radar

The map shows coastlines, rivers, docks, roads and local place names, with more detail as you zoom in. It follows your Omarchy palette and loads the visible area from OpenFreeMap, caching map data locally. When detailed coverage is unavailable, it displays the bundled offline map, identified by the source label below the radar. The offline map has generalized coastlines and may omit narrow channels; it also provides coverage near the poles.

Control	Action
Boat icon in the bar	Open or close the panel; return to the panel from the expanded window.
Expand icon (diagonal arrows, top right)	Switch between the panel and expanded window, keeping zoom and selection.
Zoom buttons (+ and −)	Gradually zoom in or out, between 1× and 64×.
Mouse wheel over the radar	Scroll up to zoom in, down to zoom out, keeping the map point under the pointer fixed within loaded coverage.
Map drag	Move around the loaded area after zooming in.
Center button (crosshair, beside zoom)	Return to your position and reset zoom to 1×.
Vessel on the map or in the list	Select a vessel to see its details. Selecting from the list also brings it into view on the map.
External link icon beside the vessel name	Open its VesselFinder details page by IMO, or search by MMSI when IMO is unavailable.
Type filters below the radar	Show or hide cargo, tanker, passenger, fishing, pleasure and other vessels. Each filter shows the type's color and number of vessels.
Status button beside the location	Click to pause reception; click again when it reads PAUSED to resume. Last positions remain visible while paused.
Settings button in the footer	Change location, API key, range and units.
Keyboard icon (top right)	Open the shortcut guide. You can also press ? or F1.

The expanded window places vessel details beside the radar when there is enough room. It can be maximized using your normal window-manager controls. Closing it leaves Vessel running in the bar.

The Settings button stays visible in the footer while you scroll. To restart reception, press R in the radar view or middle-click the boat icon in the bar.

Keyboard controls

With the radar view focused:

Key	Action
W A S D or arrow keys	Pan after zooming in.
+ / = / −	Zoom in or out.
0 / Home	Return to your position and reset zoom.
, / .	Select and reveal the previous or next vessel.
1–6	Show or hide a vessel type, in the order shown below the radar.
T	Show all vessel types.
Space / P	Pause or resume reception.
R	Restart reception. Enter also reconnects when no control consumes the key.
F	Switch between the panel and expanded window.
<	Open Settings.
Page Up / Page Down	Scroll the panel.
Tab / Shift+Tab	Focus the next or previous control.
Enter / Space	Activate the focused control.
? / F1	Open the keyboard guide.
Escape	Close the guide first, then Settings, then the current view.

When the vessel list has focus, Up / Down selects vessels. In Settings, use Tab to reach fields, search results and buttons, type normally, and use Space to activate options. Focused settings controls scroll into view automatically. Letter shortcuts are inactive while editing Settings, and Ctrl/Alt/Super combinations are left to the desktop.

Markers and colors

Filled dots indicate stationary vessels (reported speed below 0.5 knots); stationary does not necessarily mean moored or anchored, so check STATUS in the vessel details. Moving vessels use a triangle, rotated to the reported course, or to the reported heading when course is unavailable; without either, its orientation does not indicate direction. Hollow circles indicate unknown speed. The selected vessel has a ring. Positions fade after five minutes and expire thirty minutes after their last report.

Colors show the vessel type, using your theme's green, red, blue, orange and magenta for cargo, tanker, passenger, fishing and pleasure craft (including sailing). Other and unidentified vessels use the text color. Types arrive with static data, so a new contact may appear as other at first.

Filters

The type filters below the radar double as the color legend and show how many vessels of each type are in range, including hidden ones. Click a filter or press 1–6 to hide or show a type; T shows all. Filters apply to the radar, the list and vessel navigation. They reset when the shell restarts or the monitored location changes.

Recent tracks

The selected vessel shows a fading line of its recent track: up to 20 positions from the last thirty minutes, at least 90 seconds apart while it moves. Implausible jumps restart the track. At long ranges a slow vessel's track can stay hidden under its marker for several minutes; zoom in to follow it.

Closing the radar keeps recent contacts, details and tracks for thirty minutes. When you reopen it, contacts appear at once and each track continues from its last saved position to the next report received.

Vessel details

Details show distance, bearing and speed; navigational status, course and hull size; destination, MMSI and IMO; ETA, call sign and draught. Values not yet received appear as —: static data such as ETA or draught is broadcast every few minutes, and Class B vessels report no status, ETA or draught. ETA is shown as broadcast, in UTC and without a year.

Status

VIEW shows the visible radius. The contact counter shows visible vessels versus all received vessels in range. The list covers the full configured range.

LIVE indicates incoming reports, LISTENING an active connection awaiting reports, and PAUSED a saved view with reception stopped. Reception and all network downloads stop automatically when no compact panel or expanded window is open. Opening either view resumes reception unless you paused it manually. With multiple monitors, downloads continue while at least one view is open. Click PAUSED again to resume. The same control is reachable with Tab and activates with Enter or Space. REJECTED indicates a credential, subscription area or connection limit issue.

Update

omarchy plugin update simoz.vessel --yes
omarchy-shell shell rescanPlugins

Release notes are in the changelog.

Remove

omarchy plugin remove simoz.vessel

Saved preferences and the API key remain in ~/.config/omarchy-vessel/, the Python runtime remains in ~/.local/share/omarchy-vessel/, and map tiles and recent contacts remain in ~/.cache/omarchy-vessel/ (or the corresponding $XDG_CONFIG_HOME, $XDG_DATA_HOME and $XDG_CACHE_HOME locations). Remove these directories if you also want to delete Vessel's saved data.

Data and privacy

Vessel is built for watching nearby traffic. Coverage and reported destinations depend on the selected provider, receiver coverage and the vessels transmitting. Missing destinations appear as —; otherwise the text is shown as received and may contain abbreviations or port codes.

• OpenWaters (default) receives the geographic area to monitor and your optional OpenWaters token. It aggregates multiple AIS sources; the original attributions are retained in receiver snapshots. Source-specific terms apply: see OpenWaters sources and licensing.
• AISStream, when selected, receives your AISStream API key and the geographic area to monitor. Provider switching is manual; credentials are never shared between services.
• VesselFinder opens in your default browser only when you activate the external link beside a vessel name. It receives the numeric IMO or MMSI and your browser connection; Vessel does not download vessel photos. Tab reuse depends on the browser.
• Photon / OpenStreetMap provides city search from the name you enter.
• ipwho.is provides approximate location from your public IP when enabled.
• Recent contacts are saved locally, never sent anywhere, in $XDG_CACHE_HOME/omarchy-vessel/fleet.json (normally ~/.cache/omarchy-vessel/fleet.json, owner-only). The file holds received vessel data and tracks near your monitored location. Entries older than thirty minutes are discarded when it is read, and a file with nothing recent left, or saved for another location, is deleted when reception next starts. Delete it to clear the history.
• Natural Earth coastlines and GeoNames city labels are bundled with the plugin.
• OpenFreeMap receives requests for the map tiles you view, which reveal the viewed area and your IP address. These requests are independent of AIS reception and may continue while reception is paused and the map is open. No AIS keys or vessel positions are sent. Detailed tiles are stored under $XDG_CACHE_HOME/omarchy-vessel/tiles (normally ~/.cache/omarchy-vessel/tiles); above 128 MiB the cache is trimmed to 96 MiB after a batch, so downloads can temporarily exceed that threshold. Map data attribution is shown below the radar; see OpenFreeMap and OpenStreetMap copyright.

Code is licensed under MIT. Natural Earth data is public domain; GeoNames data is licensed under CC BY 4.0. See data sources and attribution.

Development and troubleshooting · Security review