luxtools-client/README.md

luxtools-client

Small local HTTP helper that lets the Dokuwiki plugin luxtools open folders on the same machine.

This program runs on the user’s machine and listens on a loopback address only (defaults to 127.0.0.1:8765). The plugin calls it to open a folder in the OS file manager.

What it does

• Exposes GET /health for a simple health check.
• Exposes GET /open?path=... and POST /open to open a folder.
• Normalizes and validates the requested path:
  • Accepts absolute paths only.
  • If a file path is provided, it opens the containing directory.
  • Accepts file://... URLs (handy when the caller passes a file URL).
• Optionally restricts which folders can be opened via -allow prefixes.

Build

Requires Go 1.22+.

go build -o luxtools-client .

Run

./luxtools-client

On startup, if you don’t pass -token, the server generates a random token and prints it to the logs. Put that token into the Dokuwiki plugin configuration.

Flags

• -listen (default 127.0.0.1:8765): listen address (host:port). Must be loopback.
• -token (default empty): shared secret token. If empty, a token is generated and logged at startup.
• -allow (repeatable): allowed path prefix. If you specify one or more, the requested path must start with one of them.

Examples:

# Listen on a different local port
./luxtools-client -listen 127.0.0.1:9000

# Use an explicit token (recommended for stable config)
./luxtools-client -token "your-shared-secret"

# Restrict opens to your home directory (repeat -allow as needed)
./luxtools-client -allow "$HOME"

Install as a service

The scripts below install (or update) the client as a service that starts automatically with the system. They assume the client binary already exists in the same folder as the scripts. During install/update, the scripts prompt you for the shared token (press Enter to keep the current token, if already configured).

Linux (systemd)

Install / update:

./install-linux.sh

Optional flags:

# Change listen address (still must be loopback)
./install-linux.sh --listen 127.0.0.1:9000

# Restrict allowed folders (repeatable)
./install-linux.sh --allow "$HOME" --allow "/mnt/data"

Uninstall:

./uninstall-linux.sh

Keep token/config on uninstall:

./uninstall-linux.sh --keep-config

Notes:

• Installs to /opt/luxtools-client/luxtools-client
• Creates /etc/systemd/system/luxtools-client.service
• Stores config (including the generated token) in /etc/luxtools-client/luxtools-client.env

Windows (Service)

Run from an elevated (Administrator) Command Prompt.

Install / update:

install-windows.bat

Optional flags:

install-windows.bat --listen 127.0.0.1:9000

Uninstall:

uninstall-windows.bat

Keep token/config on uninstall:

uninstall-windows.bat --keep-config

Notes:

• Installs to %ProgramFiles%\LuxtoolsClient\luxtools-client.exe
• Stores the generated token in %ProgramData%\LuxtoolsClient\token.txt

API

Auth

Requests must include the token using the X-Luxtools-Token header.

• Header: X-Luxtools-Token: <token>
• For GET /open, a token=... query parameter is also accepted as a fallback.

GET /health

Returns JSON:

{"ok": true, "time": "2026-01-05T12:34:56Z"}

POST /open

Request body:

{"path": "/absolute/path"}

Response:

{"ok": true, "message": "opened"}

Example:

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Luxtools-Token: your-shared-secret' \
  --data '{"path":"/tmp"}' \
  http://127.0.0.1:8765/open

GET /open?path=...

For GET callers, success returns 204 No Content (to reduce console noise in certain callers).

Example:

curl -i \
  -H 'X-Luxtools-Token: your-shared-secret' \
  'http://127.0.0.1:8765/open?path=/tmp'

OS support

• Linux: uses xdg-open.
• Windows: uses explorer.exe.

Notes / security

• The server refuses to bind to non-loopback addresses.
• Use -allow to prevent opening arbitrary folders if other local processes can reach the port.