server.lua

Which Lurker instance to talk to, and how to sign in to it. This is the server table in the config. On Lurker 2.3.0 or newer, url is the only thing you need to set.

Changes here take effect the next time luir starts. F5 reloads everything else but leaves the connection alone.

Signing in

On Lurker 2.3.0 or newer there is nothing to set up. The first time luir connects, it prints an address, tries to open it in your browser, and asks for a code:

1. Open the address and sign in to Lurker.
2. Approve luir. The page then shows a code.
3. Paste the code into luir.

That approves luir with OAuth, so it never handles your password. The token it is given never expires, and luir keeps it in auth.json beside the config, where on Linux and macOS only you can read it.

It works over SSH too. Nothing has to reach back to the machine luir runs on, so open the address wherever you have a browser. luir does not try to open one itself over SSH, or where there is no display.

luir login and luir logout

If luir logout cannot revoke the token on the server, it still forgets it, and tells you to revoke luir in Lurker under Settings, Authorized apps. Revoking it there works at any time: luir notices on its next start and asks for approval again.

When luir has been approved before and the approval page shows an error instead of a code, press enter at the prompt, and luir starts again with a fresh registration.

Older servers, and scripts

Servers older than Lurker 2.3.0 have no browser sign-in, so luir falls back to a username and password, and mints a fresh 30-day session token each time it starts:

return {
  url      = "https://lurker.example.com",
  username = "you",
  password = "hunter2",
}

A newer server uses the same fallback when luir starts with no terminal to ask in, such as from a script, and when luir cannot reach the server to ask whether browser sign-in is offered. Otherwise browser sign-in wins, even when a username and password are set.

With no terminal and no password, luir stops and asks you to run luir login in a terminal once. After that, the token it keeps is used, script or not.

The order luir tries

luir uses the first of these it finds:

1. the LURKER_TOKEN environment variable
2. token
3. token_command
4. the token kept from approving luir, unless the server says it was revoked
5. approving luir in a browser, when the server offers it and there is a terminal
6. username and password

A blank value counts as not set, and a token_command that prints nothing falls through to the next step.

A token you give luir yourself can be a session token from POST /api/auth/login/token, or an OAuth access token. API tokens from /settings/api-tokens fail with a 401, because they authenticate Lurker's MCP endpoint only.

Keeping secrets out of the file

Being Lua, server.lua can read a token or password from the environment, from a variable of whatever name you like:

password = os.getenv("LURKER_PASSWORD"),

Or hand the job to a password manager with token_command:

token_command = "pass show lurker/token",

Options

url string, default ""

The base address of your Lurker instance, such as "https://lurker.example.com". The WebSocket address is worked out from it.

luir will not connect without it, and it must be a valid URL. Browser sign-in happens at this address too, unless hosted is set. luir --demo needs no server, so it runs without one.

username string, optional

Your Lurker username, for signing in with a password: on servers older than Lurker 2.3.0, or when luir runs with no terminal. With password set too, luir signs in with POST /api/auth/login/token each time it starts, and gets a session token that lasts 30 days.

With hosted = true, this is the email address you sign in to app.lurker.chat with.

password string, optional

The password for username.

token string, optional

A token you already have: a session token from POST /api/auth/login/token, which expires after 30 days, or an OAuth access token. An API token from the web UI's /settings/api-tokens fails with a 401.

Checked after LURKER_TOKEN and before token_command.

token_command string, optional

A command that prints a token on standard output, to keep it out of this file. It is run with sh -c, or on Windows with the shell COMSPEC names, which is cmd.exe unless it has been changed. Write it for whichever shell the machine running luir actually has.

If the command exits with an error, luir stops and shows what it wrote to standard error.

hosted boolean, default false

Sign in through the hosted service at app.lurker.chat rather than your own instance. Browser approval happens there, and so does a username and password sign-in, where username is your email address.

insecure boolean, default false

Accept a TLS certificate that cannot be verified, such as the self-signed one on a self-hosted instance. Only turn this on for a host you trust: it gives up the protection TLS is there for.

reconnect_min_secs integer, default 1

How long to wait before the first attempt to reconnect after the connection drops, in seconds. Anything below 1 counts as 1.

reconnect_max_secs integer, default 30

The longest wait between reconnect attempts, in seconds. Anything below 1 counts as 1.