If you already live in the terminal and rely on Taskwarrior to manage your tasks, wui gives you a fast, keyboard-driven interface to do it all without leaving the command line.

Built with Go and Bubbletea, wui is designed for speed, simplicity, and respect for the Taskwarrior workflow you already know. When you’re away from the terminal, the same tasks are a browser tab away with the web GUI.

wui

That’s it. Press ? for help.

Why wui?

  • Instant startup — the TUI is a single binary: no loading screens, no Electron
  • Vim-style navigation — h j k l, g G, Ctrl+d Ctrl+u — feels like home
  • Taskwarrior-native filtering — use the same filter syntax you already know (+work due:tomorrow project:Home)
  • Grouped views — browse tasks organized by project or tag, drill in with Enter, back out with Esc
  • Batch operations — select multiple tasks with Space, then act on all of them at once
  • Custom commands — wire up any key to run a shell command with task data (xdg-open {{.url}}, copy to clipboard, git clone, etc.)
  • Google Calendar sync — push tasks to your calendar with wui sync
  • Web GUI — run wui gui for a browser UI that works on desktop and phone, installable as an app
  • REST API server — run wui serve to expose the Taskwarrior backend over HTTP for Flutter, web, or any other client
  • Fully configurable — tabs, columns, keybindings, themes, sort order — your workflow, your rules
  • Respects your .taskrc — reads your existing Taskwarrior contexts and settings

Features at a Glance

FeatureDescription
Customizable tabsDefine any number of tabs with their own Taskwarrior filters and sort order
Projects & Tags viewsSpecial grouped views with task counts — drill into any group
Search tabPersistent search across all tasks (pending, completed, deleted) using Taskwarrior filters
Task detail sidebarFull metadata, annotations, dependencies — scrollable with Ctrl+d/u
Multi-selectSelect tasks with Space, then batch-apply done, modify, annotate, delete
Quick modifyPress m to modify tasks inline (due:tomorrow +urgent priority:H)
Markdown exportPress M to copy tasks to clipboard as markdown (* [ ] Description (uuid))
Annotation linksPress o to open URLs and file paths found in annotations
Custom commandsMap any key to a shell command with {{.field}} templates
Flexible sortingPer-tab sorting: alphabetic, due, scheduled, created, modified — with reverse option
Short viewCompact multi-line layout for narrow terminals (auto or forced)
Theme engineDark and light base themes with full ANSI 256-color customization
Custom keybindingsRemap every action to your preferred keys
Date & time pickerInteractive calendar widget for selecting due/scheduled dates with time support
AutocompleteTab-completion for projects and tags when creating or modifying tasks
Task validationConfigurable guards: warn before completing tasks with TODO annotations or unresolved blockers
Google Calendar syncOne-way sync to Google Calendar with priority color-coding
Web GUIBrowser UI with the same tabs and filters, mobile gestures, and PWA install — see Web GUI
CLI integration--search flag to open with a pre-applied filter (great for scripts and aliases)

Installation

Requirements

  • Taskwarrior 3.x installed and in your PATH
  • Go 1.24+ (for building from source)
  • Terminal with 256-color support (recommended)

Install with Go

go install github.com/clobrano/wui@latest

Build from source

git clone https://github.com/clobrano/wui.git
cd wui
make build
sudo make install

Quick Start

# Launch the TUI
wui

# Open straight into a search
wui --search "project:Home +urgent"

# Open the web GUI in your browser (http://localhost:7008)
wui gui

# Sync tasks to Google Calendar
wui sync

# Start the REST API server (default: localhost:7007)
wui serve

# Show version
wui version

Keyboard Shortcuts

wui uses vim-style keybindings by default. Every binding is customizable.

KeyAction
j / ↓Move down
k / ↑Move up
gJump to first task
GJump to last task
Tab / l / →Next tab
Shift+Tab / h / ←Previous tab
1–9Quick-jump to task or tab

Task Actions

KeyAction
dMark task(s) done
sStart / Stop task(s)
xDelete task(s) (with confirmation)
eEdit task in $EDITOR
nCreate new task
mQuick modify task(s) — e.g. due:tomorrow +urgent
MExport task(s) as markdown to clipboard
aAdd annotation to task(s)
oOpen URL or file path from annotation
uUndo last operation
SpaceToggle multi-select on current task
EscClear selection

Views & Filtering

KeyAction
EnterToggle sidebar / Drill into group
EscClose sidebar / Back to group list
/Enter filter mode (Taskwarrior syntax)
rRefresh task list
?Toggle help screen
qQuit
KeyAction
Ctrl+d / Ctrl+fScroll down (half / full page)
Ctrl+u / Ctrl+bScroll up (half / full page)

Tip: Dates with time are supported: due:2026-03-15T14:30 or scheduled:2026-03-15T09:00. Times are displayed only when they are not midnight.

Configuration

wui reads from ~/.config/wui/config.yaml (created automatically on first run).

Tabs

Tabs are the heart of wui. Each tab defines a Taskwarrior filter, optional sort order, and optional visible columns. You can add, remove, and reorder tabs freely.

tui:
  tabs:
    - name: "Next"
      filter: "( status:pending or status:active ) -WAITING"

    - name: "Today"
      filter: "due:today"
      sort: "due"

    - name: "Urgent"
      filter: "+urgent"

    - name: "Work"
      filter: "+work -someday"
      sort: "alphabetic"

    - name: "Projects"                           # Special name → grouped view
      filter: "status:pending or status:active"

    - name: "Tags"                               # Special name → grouped view
      filter: "status:pending or status:active"

    - name: "Recent"
      filter: "status:pending"
      sort: "modified"
      reverse: true                              # Most recently modified first

Special tab names:

  • Search — always auto-prepended as the first tab (⌕). Searches across all statuses by default. Cannot be removed or reordered.
  • Projects — shows tasks grouped by project with counts. Press Enter to drill in.
  • Tags — shows tasks grouped by tag with counts. Press Enter to drill in.

Renaming “Projects” or “Tags” to anything else turns them into regular flat-list tabs.

Sorting

Each tab supports per-tab sorting:

Sort valueDescription
alphabetic (or alpha, description)Sort by description, case-insensitive
dueSort by due date (no-date tasks last)
scheduledSort by scheduled date (no-date tasks last)
created (or entry)Sort by creation date
modifiedSort by modification date (no-date tasks last)

Add reverse: true to invert the order. Completed tasks always sort to the bottom.

Columns

Choose the global default columns for the task list (case-insensitive). A tab can override them with its own columns; omitted or empty tab columns use this global list:

tui:
  columns:
    - id
    - project
    - priority
    - due
    - tags
    - description
  tabs:
    - name: "Inbox"
      filter: "status:pending +in"
      columns:
        - id
        - description
    - name: "Next"
      filter: "status:pending -WAITING"
      columns:
        - id
        - project
        - due
        - description

Available columns include id, uuid, project, priority, status, tags, description, date fields (due, scheduled, wait, start, entry, modified, end), urgency, annotation, and dependency. Custom labels and lengths are also supported.

tui:
  sidebar_width: 33  # Percentage of terminal width (1–100)

Short View (Narrow Terminals)

When the terminal is less than 80 columns wide, wui switches to a compact layout:

▶ Fix login page crash
  DUE:  2026-02-20
  TAGS: +bug, +frontend

Configure up to 3 fields below each task description:

tui:
  narrow_view_fields:
    - name: due
      label: "DUE"
    - name: tags
      label: "TAGS"
    - name: project
      label: "PROJECT"

  # Force narrow view at any terminal width:
  # force_small_screen: true

Keybindings

Remap any action:

tui:
  keybindings:
    quit: q
    help: "?"
    up: k
    down: j
    first: g
    last: G
    page_up: ctrl+u
    page_down: ctrl+d
    done: d
    delete: x
    edit: e
    modify: m
    annotate: a
    new: n
    undo: u
    filter: "/"
    refresh: r

Custom Commands

Map any key to a shell command using {{.fieldname}} templates. All Taskwarrior fields and custom UDAs are available.

tui:
  custom_commands:
    O:
      name: "Open URL"
      command: "xdg-open {{.url}}"
      description: "Opens the task's URL in default browser"

    "1":
      name: "Copy Description"
      command: "echo {{.description}} | xclip -selection clipboard"
      description: "Copy task description to clipboard"

    c:
      name: "Git Clone"
      command: "git clone {{.url}} ~/projects/{{.project}}"
      description: "Clone repository to project folder"

Custom commands appear in the help screen (?). Platform-specific examples:

PlatformCommand
Linuxxdg-open {{.url}}
macOSopen {{.url}}
Termux (Android)termux-open-url {{.url}}
Windowscmd /c start {{.url}}

If a custom command key conflicts with a built-in shortcut, wui warns on exit. Add silence_shortcut_override_warnings: true to suppress this.

For the full reference, see docs/custom-commands.md.

Themes

wui ships with dark and light base themes. Override any color with ANSI 256-color codes:

tui:
  theme:
    name: dark  # "dark" or "light" (any other name uses dark as base)

    # Priority colors
    # priority_high: "9"
    # priority_medium: "11"
    # priority_low: "12"

    # Due date colors
    # due_overdue: "9"
    # due_today: "11"
    # due_soon: "11"

    # Status colors
    # status_active: "15"
    # status_waiting: "8"
    # status_completed: "8"

    # UI elements
    # header_fg: "12"
    # footer_fg: "246"
    # separator_fg: "8"
    # selection_bg: "12"
    # selection_fg: "0"
    # sidebar_border: "8"
    # sidebar_title: "12"
    # label_fg: "12"
    # value_fg: "15"
    # dim_fg: "8"
    # error_fg: "9"
    # success_fg: "10"
    # tag_fg: "14"

    # Tab colors
    # section_active_fg: "15"
    # section_active_bg: "63"
    # section_inactive_fg: "246"

Color values are ANSI 8-bit codes (0–255). Standard colors 0–15 work everywhere; 16–255 require 256-color terminal support.

Filtering

wui uses Taskwarrior’s native filter syntax. Press / to filter:

+work -someday                 # Tag include/exclude
project:Home due:tomorrow      # Field matches
status:pending priority:H      # Status and priority
(+urgent or +important)        # Boolean logic

The Search tab (⌕) searches across all statuses by default. Other tabs filter within their own scope.

Google Calendar Sync

Sync your tasks to Google Calendar as color-coded all-day events.

Setup

  1. Create a project in Google Cloud Console and enable the Google Calendar API
  2. Create OAuth 2.0 credentials (Desktop app) with http://localhost:8080 as redirect URI
  3. Download credentials.json to ~/.config/wui/
  4. Configure in config.yaml:
calendar_sync:
  enabled: true
  calendar_name: "Tasks"
  task_filter: "status:pending or status:completed"
  credentials_path: ~/.config/wui/credentials.json
  token_path: ~/.config/wui/token.json

Usage

# Sync using config settings
wui sync

# Override calendar or filter on the fly
wui sync --calendar "Work" --filter "+work due.before:eow"
wui sync --calendar "Urgent" --filter "+urgent priority:H"

On first run, you’ll authorize via browser. The token is saved to ~/.config/wui/token.json.

How it works

  • Tasks always sync with their exact due (or scheduled) time to Google Calendar as timed events, even if the time is midnight
  • Set allDay:true UDA to create an all-day event instead, which ignores the specific time
  • Timed events use the dur UDA for their length (e.g. dur:30min, dur:1h30min); without it they default to 15 minutes
  • Events include UUID, project, tags, and status in the description
  • Completed tasks show a ✓ checkmark in the title
  • Events are color-coded by priority (red = high, yellow = medium)
  • Existing events are updated when tasks change
  • Sync is one-way: Taskwarrior → Google Calendar

Tip: dur and allDay are User Defined Attributes. Define them once in your .taskrc to use them:

uda.dur.type=duration
uda.dur.label=Duration
uda.allDay.type=string
uda.allDay.label=All Day

Then set them on tasks:

  • Timed event: task add "Standup" due:2026-03-15T09:00 dur:15min
  • Timed event at midnight: task add "Night shift" due:2026-03-15T00:00 (exact time is preserved)
  • All-day event: task add "Holiday" due:2026-12-25 allDay:true

CLI Reference

wui                              Launch the TUI
wui version                      Print version info
wui sync                         Sync tasks to Google Calendar
wui serve                        Start the REST API server
wui gui                          Start the web GUI (and the REST API if it isn't running)

Flags (all commands):
  --config string                Config file path (default: ~/.config/wui/config.yaml)
  --taskrc string                Taskrc file path (default: ~/.taskrc)
  --task-bin string              Task binary path (default: /usr/local/bin/task)
  --log-level string             Log level: debug, info, warn, error (default: error)
  --log-format string            Log format: text, json (default: text)

wui flags:
  --search string                Open in Search tab with a pre-applied filter

wui serve flags:
  --addr string                  Address to listen on (default: localhost:7007)
  --tls-cert string              Path to TLS certificate file (enables HTTPS)
  --tls-key string               Path to TLS private key file (enables HTTPS)

wui gui flags:
  --host string                  Address to listen on (default: all interfaces)
  --port int                     Port to listen on (default: 7008)
  --api-port int                 Port of the wui serve API (default: config or 7007)
  --no-browser                   Don't open the GUI in a browser on startup

Logging

Log level priority: CLI flag > WUI_LOG_LEVEL env var > config file.

Logs go to /tmp/wui.log by default. Override with WUI_LOG_FILE environment variable.

# Debug a specific session
wui --log-level debug

# Or via environment
export WUI_LOG_LEVEL=info
wui

Comparison to taskwarrior-tui

wui is inspired by taskwarrior-tui and builds on the idea with a different set of priorities:

wuitaskwarrior-tui
LanguageGoRust
FrameworkBubbleteatermbox
Grouped viewsProjects & Tags with drill-down—
Custom tabsUnlimited, with per-tab filters & sorting—
Custom commands{{.field}} template shell commands—
Calendar syncGoogle Calendar—
Multi-selectBatch operations on selected tasks—
Markdown exportCopy tasks to clipboard—
Short viewAuto-adapts to narrow terminals—

Web GUI

wui gui serves a web interface for the same Taskwarrior data, so you can check and update your tasks from a browser, another computer or your phone.

wui gui                        # http://localhost:7008, opens your browser
wui gui --port 8080            # another port
wui gui --host 127.0.0.1       # reachable from this machine only

What you get:

  • The same tabs as the TUI — Search, your configured tabs, and the grouped Projects and Tags views, all read from ~/.config/wui/config.yaml, with the same columns
  • Taskwarrior filters — type any filter (project:home +errand due.before:eow); recent filters are kept in a history you can reuse
  • Task details — all fields, clickable links in annotations, and buttons to start/stop, edit, mark done or delete; add and remove annotations in place
  • New and edit forms — a Form mode with fields for project (with autocomplete), tags, priority, due/scheduled/wait/until dates, recurrence and dependencies, or a Raw mode where you type Taskwarrior arguments directly
  • Batch actions — tick several tasks (long-press on touch screens) to complete or delete them together
  • Undo — every done or delete shows an Undo toast
  • Made for phones — compact layout on small screens; swipe a task right to complete it or left to delete it
  • Light and dark — follows your system theme
  • Installable — add it to your home screen or desktop as an app (see below)

wui gui starts the REST API for you on localhost:7007 if it isn’t already running, and forwards /api/v1/ to it, so the GUI’s port is the only one you need to expose. The GUI has no authentication: anyone who can reach the port can read and change your tasks. Keep it on your own network, or use Tailscale.

To keep it running in the background, or reach it from your other devices, see the next two sections.

Running as a daemon (Linux / systemd)

There are two ways to keep wui running in the background as a systemd user service. Pick one per machine: both read and write the same Taskwarrior data, so don’t run them side by side.

Native (make service-install)Container (deploy/)
Runswui gui (web UI on :7008, all interfaces, or 127.0.0.1 with WUI_TAILSCALE=1; API on localhost:7007)wui gui (web UI, 127.0.0.1:7008; API kept internal)
Host needsGo and TaskwarriorPodman 4.4+
Updatesgit pull && make service-installpodman auto-update from the registry
Unitwui-serve.servicewui.service (Quadlet)
Best forA box that already has TaskwarriorKeeping the host clean

Both can run the REST API only instead: natively with WUI_ARGS="serve ..." (below), in the container by changing its Exec= line (see deploy/README.md).

Native

wui runs straight from the binary as your user, so it uses your ~/.taskrc, Taskwarrior data and ~/.config/wui — no root needed. By default it runs the web GUI, the same as make serve: open http://<server>:7008 from any machine on your network.

make service-install                      # build, install, enable and start at boot (web GUI on :7008)
make service-install WUI_PORT=8080        # web GUI on another port
make service-install WUI_ARGS="serve --addr :7007"   # REST API only, e.g. for wui-android
make service-install WUI_TAILSCALE=1      # GUI on 127.0.0.1 only, served over HTTPS on your tailnet (see below)
make service-install WUI_HOST=127.0.0.1   # GUI reachable from this machine only
make service-linger                       # only needed if you installed with WUI_LINGER=0

make service-status                       # systemctl --user status wui-serve
make service-logs                         # journalctl --user -u wui-serve -f
make service-restart                      # e.g. after editing config.yaml
make service-uninstall                    # stop, disable and remove the unit

The web GUI has no authentication and, by default, is reachable by anyone on your network. If the server has a firewall, open the port (e.g. sudo firewall-cmd --add-port=7008/tcp --permanent && sudo firewall-cmd --reload, or sudo ufw allow 7008/tcp). For access from outside your network, use Tailscale rather than opening it to the internet. With WUI_TAILSCALE=1 the GUI listens on 127.0.0.1 only and other devices reach it through https://<machine>.<tailnet>.ts.net, so there is no port to open; set WUI_HOST= to keep it on all interfaces as well.

By default service-install also runs loginctl enable-linger $USER, so your user’s services start at boot and keep running with nobody logged in (it may ask for sudo/polkit). On a desktop where you only want it while logged in, use make service-install WUI_LINGER=0. service-uninstall leaves linger on, since other user services may rely on it; turn it off with loginctl disable-linger $USER.

Re-run make service-install to upgrade the binary or change options. Other variables: WUI_HOST (GUI listen address; default all interfaces, or 127.0.0.1 with WUI_TAILSCALE=1), WUI_LOG_LEVEL (default info) and WUI_BIN (default: where go install puts wui). The unit template is in deploy/systemd/wui-serve.service.in.

Setting WUI_LOG_FILE=- makes wui log to stderr instead of /tmp/wui.log; the service does this so its logs go to the journal. wui gui --no-browser skips opening a browser on startup; the service uses it.

Container

make container-install                    # install the Podman Quadlet unit, start it, start at boot
make container-install WUI_TAILSCALE=1    # also serve the GUI over HTTPS on your tailnet (see below)
make container-uninstall                  # stop it and remove the unit

See deploy/README.md for building the image and the details of the Quadlet unit.

Installing the web GUI as an app (PWA)

The web GUI is a Progressive Web App: Chrome, Edge and Android offer Install app (or Add to Home screen) in the browser menu, and Safari on iOS has Share → Add to Home Screen. Once installed, wui opens in its own window with its own icon, and shows the last loaded page, or an offline notice, while the server can’t be reached. Task data is always fetched live.

Browsers only allow installing from a secure origin: http://localhost:7008 works, but http://<server>:7008 from another machine does not. To install on other devices, put the GUI behind HTTPS. The deploys can do this with Tailscale Serve, which works on the free plan:

  1. In the Tailscale admin console, DNS page: make sure MagicDNS is on, then click Enable HTTPS under HTTPS Certificates. This is needed once per tailnet.

  2. Install with WUI_TAILSCALE=1:

    make service-install WUI_TAILSCALE=1      # native
    make container-install WUI_TAILSCALE=1    # container
    

    Or, for a wui that is already running: make tailscale-serve (add TAILSCALE_PORT=… if the GUI isn’t on 7008).

  3. Open the printed https://<machine>.<tailnet>.ts.net address on a device connected to your tailnet, and install the app from the browser menu.

Tailscale gets and renews the certificate itself and remembers this setting across reboots. Changing it needs root, so the targets run sudo tailscale serve …; if you made your user a Tailscale operator (sudo tailscale set --operator=$USER), pass TAILSCALE_SUDO=. Use make tailscale-serve-status to check it and make tailscale-serve-off to stop it. Note that the machine and tailnet names (not the GUI itself) end up in public certificate transparency logs.

Any other reverse proxy with a certificate (Caddy, nginx, …) works too.

API Server

wui serve starts a lightweight REST/JSON HTTP server backed by the same Taskwarrior client that the TUI uses. This lets any HTTP-capable client — Flutter, a web app, scripts, other terminals — drive the same business logic without running the TUI.

# Listen on localhost only (default)
wui serve

# Listen on all interfaces (e.g. to reach from a phone on the same network)
wui serve --addr :7007

The server shuts down cleanly on Ctrl+C.

Endpoints

All paths are under /api/v1. Requests and responses use JSON.

MethodPathDescription
GET/api/v1/tasksList tasks. Optional ?filter= query param uses Taskwarrior filter syntax.
POST/api/v1/tasksCreate a task. Body: {"description": "Buy milk +shopping"}
PUT/api/v1/tasks/{uuid}Modify a task. Body: {"modifications": "priority:H due:tomorrow"}
DELETE/api/v1/tasks/{uuid}Delete a task.
POST/api/v1/tasks/{uuid}/doneMark a task done.
POST/api/v1/tasks/{uuid}/startStart a task.
POST/api/v1/tasks/{uuid}/stopStop a task.
POST/api/v1/tasks/{uuid}/annotateAdd an annotation. Body: {"text": "See ticket #42"}
DELETE/api/v1/tasks/{uuid}/annotateRemove an annotation. Body: {"description": "exact text"}
POST/api/v1/undoUndo the last Taskwarrior operation.
GET/api/v1/projectsList project summaries with completion percentages.
GET/api/v1/tagsList all tags in use. Returns ["tag1", "tag2", ...]
GET/api/v1/udasList User Defined Attribute names. Returns ["uda1", "uda2", ...]
GET/api/v1/versionwui and Taskwarrior version info.

Quick Examples

# List pending tasks in a project
curl "http://localhost:7007/api/v1/tasks?filter=project:Home+status:pending"

# Add a task
curl -X POST http://localhost:7007/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"description": "Fix the leak +home"}'

# Mark a task done
curl -X POST http://localhost:7007/api/v1/tasks/<uuid>/done

# Modify priority and due date
curl -X PUT http://localhost:7007/api/v1/tasks/<uuid> \
  -H "Content-Type: application/json" \
  -d '{"modifications": "priority:H due:friday"}'

Response Format

GET /api/v1/tasks returns a JSON array of task objects. All date fields use RFC 3339 (UTC):

[
  {
    "id": 1,
    "uuid": "a1b2c3d4-...",
    "description": "Fix the leak",
    "project": "Home",
    "tags": ["home"],
    "priority": "H",
    "status": "pending",
    "due": "2026-05-15T00:00:00Z",
    "entry": "2026-05-10T08:00:00Z",
    "urgency": 8.5,
    "annotations": [
      { "entry": "2026-05-10T09:00:00Z", "description": "Called plumber" }
    ]
  }
]

Using from the wui-android Flutter app (Android, Linux, Web)

wui-android is a Flutter front-end that can connect to wui serve instead of running the Taskwarrior binary locally. It supports Android, Linux desktop, and browser (web) builds.

Android / Linux desktop

# In the wui-android repo
flutter pub get

# Android APK
flutter build apk --release --split-per-abi
adb install build/app/outputs/flutter-apk/app-release-arm64-v8a.apk

# Linux desktop
flutter build linux --release

Open Settings in the app and set the Remote server URL to http://<host>:7007/api/v1.

Web (browser)

flutter build web --release
# Serve the output with any static file server, e.g.:
python3 -m http.server 8080 --directory build/web

Then open http://localhost:8080 in a browser. Set the Remote server URL in Settings the same way.

The web build cannot run the local Taskwarrior binary, so a running wui serve instance is required. The server already includes CORS headers, so browser requests work without any extra configuration.

Using from Flutter (custom integration)

Add the http package to your Flutter project and point it at wui serve:

import 'dart:convert';
import 'package:http/http.dart' as http;

const base = 'http://localhost:7007/api/v1';

Future<List<dynamic>> fetchTasks({String filter = ''}) async {
  final uri = Uri.parse('$base/tasks').replace(
    queryParameters: filter.isNotEmpty ? {'filter': filter} : null,
  );
  final res = await http.get(uri);
  return jsonDecode(res.body) as List<dynamic>;
}

Future<void> completeTask(String uuid) =>
    http.post(Uri.parse('$base/tasks/$uuid/done'));

Security note: The server has no built-in authentication. Run it on localhost (the default) or inside a trusted network. Do not expose it directly to the internet.

Secure access with Tailscale

When accessing wui serve from a mobile device or across machines, Tailscale is the recommended approach. Tailscale creates a WireGuard-encrypted mesh VPN between your devices — all traffic through it is encrypted at the network layer, so plain HTTP over a Tailscale connection does not expose data in transit.

1. Install Tailscale on both the server machine and the client device, then sign in:

tailscale up

2. Find your server’s Tailscale IP:

tailscale ip -4   # e.g. 100.94.12.34

3. Bind wui serve to the Tailscale interface so it is unreachable from the LAN or internet:

wui serve --addr $(tailscale ip -4):7007

4. Connect from clients using the Tailscale IP:

http://100.94.12.34:7007/api/v1

Tailscale must be running on both machines whenever the server is in use.

HTTPS with a TLS certificate: if your Tailscale plan supports tailscale cert, or if you have a certificate from another source (mkcert, Caddy, etc.), pass it via --tls-cert and --tls-key to enable native HTTPS. The flags accept any PEM-encoded certificate and RSA/ECDSA private key.

Development

See CLAUDE.md for the development guide and architecture overview.

make build       # Build binary
make test        # Run tests with coverage
make lint        # Run linter
make fmt         # Format code
make clean       # Clean build artifacts

License

MIT License — see LICENSE for details.

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

Credits