Wayseer

User guideWayseer 0.28.3Contents

Language model

With a language model configured, the palette answers questions. Press ?, type a question, and press Enter:

? which hosts were busiest in the last hour
? what changed on the storefront services since the deploy

The model answers by moving the view: it picks the lens, filter, metric and time window that show the answer, then says what they show in the narration panel. Ctrl+J shows or hides the panel. Enter on ? with nothing typed explains the focus, else the selection, else the view.

Wayseer works fully without a model. Without one, ? says no language model is configured, and the lines in Answered without a model still work.

The license

Asking the model, and its explanations, need a license key (License and keys). Without one, ?, Enter on an empty question and >ask.new send nothing: the status line says "a license key unlocks the language model" and the license panel opens. At start the status line says that the language model is off. The request log stays readable with >nl.log.

A key added applies to the next question. Removing the key refuses the next question; an answer already given stays in the narration panel.

Providers

Choose one in the config's nl section (configuration).

Claude, through Anthropic:

nl:
  provider: anthropic
  model: claude-opus-5-5          # the default
  secret_keyring: wayseer/anthropic   # or secret_file, or secret_env: ANTHROPIC_API_KEY

A local model, through Ollama. The model must support tool calls:

nl:
  provider: ollama
  model: qwen3:8b
  url: http://localhost:11434     # the default
  local_only: true

Many models under one key, through OpenCode Zen: claude-* models, and chat-completions models such as kimi-k3 or glm-5.3:

nl:
  provider: zen
  model: kimi-k3
  secret_file: ~/.config/wayseer/zen-key   # or secret_env: OPENCODE_API_KEY

Claude, Gemini and other models on Google Cloud's Vertex AI, with a service account's key file or your own gcloud login:

nl:
  provider: vertex
  model: gemini-3-pro             # or claude-sonnet-5, or publisher/model such as meta/llama-5-maverick
  region: us-east5                # the default is global
  secret_file: ~/.config/wayseer/vertex-key.json

secret_file names either of two files:

  • A service account's key: the JSON Google Cloud gives when you add a key to a service account. The project is the one the file names.
  • Your own login: the application_default_credentials.json that gcloud auth application-default login writes, on Linux in ~/.config/gcloud/. The project is the file's quota project, if it has one (gcloud auth application-default set-quota-project), and requests are charged to it.

project: my-project-123 uses that project instead, and is needed for a login without a quota project. The account or user needs the Vertex AI User role (roles/aiplatform.user) in the project. The model must be enabled there, in the Model Garden, and served in the region. If a login expires or is revoked, the answer says invalid_grant; run the gcloud command again. Wayseer reads only the file named, and never runs gcloud itself.

claude-* models are asked through Anthropic's API as Vertex serves it; other models through Vertex's OpenAI-compatible API, a bare name such as gemini-3-pro meaning Google's own. Vertex's dated names, such as claude-haiku-4-5@20251001, work as they are.

Claude models that think adaptively (Opus and Sonnet 4.6 and later) think before they answer; older ones, and Haiku 4.5, answer without thinking.

The key is read from the file, variable or keyring entry named (secrets); it never goes in the config. url may use http:// only for this machine or network.

What is sent

Only what the view shows: the lens, focus, selection, filter and time window; up to 50 of the entities in view with their kind, name and status; and the names of the metrics and attribute keys the world has. Never the config file, a secret, or who you are. Each tool lists the values it takes, such as the lenses; one that takes an entity or metric lists them only while there are 50 or fewer, and otherwise the model finds them with the tools below.

To answer, the model may also ask for more, read-only, through these tools:

  • search_entities, list_metrics, query_series, query_events and describe_entity.
  • list_flows gives an entity's largest flows in and out, as Flow draws them: the entity at the other end, by name and kind, and its rate in requests, bytes or messages per second, with entities linked as the same counted as one. It reads only edges already in the world, never a module's query.
  • list_places gives the places entities are at, as Geo shows them, worst first: each place's name from your config's places: (or its point, when a module sent one config does not name), how many entities are there and their worst status, and how many have no place. Given a place, it lists what is there by kind and status. It reads only places already in the world, so a place's name is never sent anywhere to be looked up.
  • list_changes reads the same groups as the list of what changed, newest first, optionally only those since a span ago, and says which you have not seen; so "what did I miss?" is answered from what Wayseer saw, not guessed.

The model moves the view only through the commands marked with a model tool in Commands. It can:

  • set the lens, time window and filter;
  • focus or open an entity;
  • show a metric in Grid, or a measure in Treemap (show_treemap);
  • narrow Flow to an entity's traffic (show_flow);
  • show Geo at a place or following an entity (show_map);
  • put two entities side by side (compare), or the focus beside itself earlier (compare_with_earlier);
  • save or go to bookmarks.

It cannot change anything outside Wayseer except the bookmarks it saves, and the actions you confirm (below).

Actions

When your config allows an action on some module instance, the model is also offered two tools; with none allowed, it is not told they exist.

  • list_actions gives the actions allowed on an entity: each one's ID, what it changes and its parameters with their bounds.
  • propose_action opens the confirm panel on one, marked "Proposed by the model", with the parameters the model chose. You can change them there before Y. The model is told declined, ok with the module's message, or failed with its error, which has passwords and tokens taken out.

The model proposes, but only your Y runs anything. The panel opens whatever confirm says, and confirm: true asks nothing more for it. A proposal left unanswered for two minutes closes as declined, and so does one whose question ends, as when you start a new conversation. Esc in the panel declines the proposal; it does not cancel the question, so the model hears the answer.

One question may propose one action; a second is refused, as is a proposal while you have the action panel open or an action is running. Every proposal is in the action log with model as who proposed it.

The request log

Every request sent is kept, without keys, in nl-log.jsonl, on Linux usually ~/.local/state/wayseer/nl-log.jsonl (where files are kept), readable only by you. >nl.log shows the last ones.

Confirm, local only and the budget

  • confirm: true asks before each move the model makes: Y allows it, N declines.
  • local_only: true refuses any model not on this machine or network.
  • A conversation may spend 200,000 tokens. After that, >ask.new starts a new one; so does it any time you want the model to forget what was asked before. A single request larger than that is not sent, and the answer says so.
  • Esc cancels a question while the model is still answering, unless an action panel is open, where it declines.