Lumi setup: local search, CLI accounts and custom APIs
Find a local file first, then connect a CLI account, local model or custom API. Verify a complete answer, the actual model and the account handling usage.
Contents
Lumi runs file search and AI questions through different paths. Search checks the operating system’s index; a question goes to the CLI or API you select. Start by finding a known file, choose one model connection, send a harmless short question, then check the actual model and usage. Finding a document does not mean the model has read it, and a CLI label does not prove that subscription credits paid for the request.
The interface and runner behavior below refer to this pinned Lumi revision. Other versions may change the controls or model menu. Copy model IDs from the current service rather than treating an old menu as a model catalog.
Install Lumi and test file search separately
Download the appropriate build from the project’s Releases. On macOS, open the DMG and drag Lumi to Applications; Windows offers an installer and a portable build. If the first launch raises a signing or security warning, verify the project source and your organization’s policy before proceeding. Do not disable system-wide security controls. See the macOS instructions and Windows instructions.
The default shortcut is Option plus the physical key immediately left of 1 on macOS, or Alt plus that key on Windows. Its printed character depends on the keyboard layout. Change a conflicting shortcut with Change in the welcome window. The field names below use the English interface.
Search for an ordinary file or application that you know exists and is indexed. Check the name and path, select the result with the arrow keys, and press Enter to open it. Option+Enter on macOS or Alt+Enter on Windows reveals the selected file in Finder or Explorer. No model API key is needed for this step. Mac search uses Spotlight; Windows uses Start-menu shortcuts for applications and Windows Search for files. Missing files are a reason to check the system index and search scope, not to replace the model. Search and shortcuts
Understand what the model receives
A file result opens or locates that file; it does not automatically attach the document to a model conversation. Even when the index matches document content, that is not the same as sending the document body.
The custom API runner normally sends a system instruction, the current conversation history and your new question. Bundled lumi Ollama models have a branch that omits the system instruction. The request construction does not automatically add every search result or arbitrary file contents. Anything you paste into the question, earlier conversation content, and the selected backend’s own processing still require a data-handling decision. Request construction
The CLI runners have different boundaries. Claude starts in the user’s home directory with WebSearch,WebFetch specified by Lumi. Codex uses a dedicated directory, --sandbox read-only, and an instruction not to run commands or read files. Gemini uses its own directory and --approval-mode plan. A working directory, a sandbox and a prompt instruction are different controls—not proof that a process cannot read other configuration or make network requests. The CLIs retain their own authentication and configuration. macOS inherits the process environment before adjusting PATH; Windows does not clear authentication variables either. macOS runners; Windows runners
Choose a request path, not a price winner
| What you already have | Start with | What to verify |
|---|---|---|
| An installed CLI and eligible account access | Claude, Codex or Gemini CLI | The active authentication method and the account whose allowance or bill changes |
| Downloaded weights for inference on your computer | A local Ollama or LM Studio server | The loaded model, execution host and any cloud forwarding; local hardware and electricity are still resources |
| A specific external model and API account | A custom API connection | Endpoint, key, exact model ID and that API account’s usage or balance |
This is a configuration decision, not a cost ranking. Subscription access, additional metered usage and local computing resources are not interchangeable charges. Do not call one route cheaper without checking its applicable subscription, usage and funding requirements.
Existing CLI: check authentication before selecting it
Configure only the CLI you intend to use. For Claude, run claude to complete the official sign-in flow and use /status in the interactive interface to inspect authentication. Pay particular attention to ANTHROPIC_API_KEY: the official documentation says a key present in non-interactive -p mode is used, and other authentication mechanisms can have higher precedence. Lumi invokes Claude with -p. An interactive session showing a subscription is therefore not enough to establish how Lumi’s request will be billed. Inspect the environment inherited by Lumi and the resulting usage without printing secret values. Claude authentication precedence
For Codex, use codex login and then codex login status. OpenAI distinguishes ChatGPT subscription sign-in from metered API-key use. Also inspect an existing custom provider configuration; Lumi’s Codex label alone cannot identify the actual backend. Codex authentication
For Gemini, run gemini and follow Sign in with Google when that is your chosen method. Google sign-in, a Gemini API key and Vertex AI are different routes. Headless invocation can reuse cached authentication; it does not automatically become a particular subscription plan. Gemini authentication
Return to Lumi and select the corresponding CLI in the model menu. After changing authentication or the launch environment, quit and reopen Lumi before verifying. Provider account, region and organization restrictions still apply; neither Lumi nor a separate API connection removes another service’s login restrictions.
Save a local or external API connection
Leave any existing answer and return to an empty input state before opening Connect a model… in the model menu. Under Service, choose Ollama, LM Studio or Other address. Fill in Name, Address, Model and API key, press Connect, then confirm that the saved connection is selected in the model menu. Connection form
Address is the Base URL, not the full question endpoint. Lumi appends /chat/completions itself. Pasting the full endpoint creates a duplicated path. Name is your descriptive label; Model must be an exact identifier accepted by the server.
| Destination | Example Address | Model and key |
|---|---|---|
| Local Ollama | http://localhost:11434/v1 | An actually downloaded local model name; the standard local server needs no cloud API key |
| Local LM Studio | http://localhost:1234/v1 | The model identifier from LM Studio; provide the server’s credential when authentication is enabled |
| BetterToken custom connection | https://www.bettertoken.ai/v1 | Your own API key and a current model ID copied from model plaza or Key Setup |
Start the Ollama or LM Studio server and prepare a usable model first. These ports are official example defaults; use your actual port if changed. localhost identifies the first network hop, not where all inference happens. For offline work, verify that weights execute locally and that the server does not forward the request to a cloud model. Ollama compatibility; LM Studio server and API
BetterToken is an optional API account here, not a replacement subscription login. Check service eligibility, create a key in your own account, follow the current key setup instructions, and confirm allowance or balance and model availability. YOUR_API_KEY and YOUR_MODEL_ID are placeholders, not usable credentials. Put the real key in the concealed key field, never in a question, screenshot or log. The documentation currently lists Russia as the service region; readers elsewhere should confirm account eligibility with the service first.
The developer-entry table in the BetterToken documentation lists https://www.bettertoken.ai/v1. Combined with Lumi’s suffix, this produces https://www.bettertoken.ai/v1/chat/completions, corresponding to the Chat Completions documentation. This is a request-format derivation, not evidence that your account has passed an end-to-end test or that every model feature works. Saving a Lumi custom connection does not rewrite your CLI’s existing provider configuration.
Verify one complete answer and its usage
Start a blank conversation, select the intended connection and ask: “Convert 2.5 inches to centimetres. Answer in one sentence without searching the web.” Send it with Cmd+Enter on macOS or Ctrl+Enter on Windows so Enter cannot open a selected file instead. Ask in ChatGPT, Cmd+Shift+Enter and Ctrl+Shift+Enter use the browser path, not this API test. Keyboard actions
Wait for the answer to finish. The expected conversion is 6.35 centimetres. With the input empty and no text selected, use Cmd+C or Ctrl+C to copy the complete reply. Save it privately with the request time and connection name, without any key. Correct arithmetic is only the content check: separately confirm a visible local file result, a complete answer, the actual provider/model and matching account usage.
For an API connection, compare the request and usage records in that account; BetterToken’s Dashboard exposes requests, token consumption and balance. For a CLI, inspect the authenticated account’s allowance or API billing. For local inference, verify the local server’s processing record and loaded model instead of looking for a cloud charge. If the service provides only aggregate usage and no per-request model evidence, record the model as unconfirmed. Asking the model to identify itself is not a substitute. BetterToken usage controls
Diagnose the failure before retrying
Press Esc to stop an active answer, then Esc again to leave its answer or error view. In this revision, changing models after a failed answer—or pressing Enter with an empty input—can resend the previous question. Leave the error state before changing connections so an unintended retry does not send the last question to another service. Stopping the client is not evidence that the server incurred no usage. Retry and escape behavior
| Symptom | Next check |
|---|---|
| Applications appear but a file does not | Check the operating system’s file index and scope; do not change the API key |
| Missing CLI or failed login | Make that CLI available through its official terminal flow; check the executable Lumi finds rather than reinstalling every tool |
401 or 403 | Read the error body; distinguish credentials from network, region or organization policy |
404 or unknown model | Remove a duplicated /chat/completions, then verify the exact model ID and local model readiness |
429 or an allowance error | Check account quota, balance and rate-limit guidance; follow the server’s retry instructions rather than looping |
HTTP 200 with blank, partial or errored output | Inspect the complete stream and final error; acceptance is not a successful answer |
The API runner explicitly handles errors inside a stream and empty replies. Text appearing briefly is therefore not completion. Correct one identified problem, send one new short question, and repeat the same four checks. Error handling
Make one ordinary file search and one harmless question work, with processing and billing ownership established, before adopting the connection for daily work.
