User guideWayseer 0.28.3Contents

Control

Another program on the same machine, such as a script or an AI agent, can drive Wayseer through its control socket. It can move the view, read what the language model can read, and propose an action. It cannot run an action: that still waits for you to press Y.

The socket is off unless your config turns it on:

control: {enabled: true}

It opens when Wayseer next starts. A change to control waits for a restart (reloading).

The license

Control and MCP need a license key (License and keys). Without one, the socket still opens when config turns it on, so a client learns why: every request is answered a license key unlocks integrations and none runs. wayseer control prints that answer and exits 1, and wayseer mcp fails every tool call with it. At start the status line says that control is off.

A key added applies to the next request. Removing the key refuses the next request; an answer already given stands.

Where it listens

The socket is a file only you can open, in a folder only you can enter:

$XDG_RUNTIME_DIR/wayseer/control.sock, usually /run/user/1000/wayseer/

~/Library/Application Support/Wayseer/control/control.sock

Windows: %LOCALAPPDATA%\Wayseer\control\control.sock

Without XDG_RUNTIME_DIR, Linux uses ~/.local/state/wayseer/control/ instead. On Windows it is a Unix socket too, which Windows 10 1803 and later support; the folder's access list names only you. Nothing listens on a network port, so no other machine can reach it.

The socket is removed when Wayseer exits. One left by a crash is replaced at the next start. If another copy of Wayseer is already listening, the second says so in the status bar and runs without one.

Trying it

wayseer control sends one request and prints the answer:

wayseer control '{"op":"run","command":"lens.show","args":{"lens":"geo"}}'
wayseer control '{"op":"tool","tool":"list_places"}'

It exits 0 when the answer is OK and 1 when it is not, or when Wayseer is not running or has control off.

Requests

Each request is one line of JSON, and each answer is one line back. A request may carry an id, which comes back on its answer, so a client can send several before reading:

{"id":1,"op":"run","command":"view.focus","args":{"ref":"demo/host/db-01"}}
{"id":1,"ok":true,"result":"now at: lens topology, focus demo/host/db-01, …; 412 entities in view"}

A request that fails answers "ok":false with an error:

{"id":2,"ok":false,"error":"app.quit is not open to control"}

commands

Lists the commands run takes: each one's id, name, and its arguments as a JSON schema.

run

Runs a command with its args, as the palette does. The answer says where the view is now.

tool

Calls one of the language model's tools by tool, with its args: search_entities, describe_entity, list_metrics, query_series, query_events, list_changes, list_flows, list_places, list_actions, and the tools that move the view.

tools

Lists the tools tool takes: each one's name, description and schema, and moves_view, whether it moves the view.

view

The view as the language model is shown it: where you are, what is in view, and the metrics and attributes there are.

ask

Puts args.question to Wayseer's own language model, as the palette's ? does, and answers with its reply once it is done.

windows

Lists the open windows: each one's window number, lens, focus, the window it follows, and in_use on the one used last.

ask needs a model in your config, and waits if the model is answering another question. The question and its answer show in the narration panel as yours do.

Arguments are strings, as in the palette: {"span":"1h"}, not {"span":3600}. Commands lists every command and its parameters.

More than one window

With more than one window open, a request acts in the window used last, unless it names one by number with window:

{"op":"run","window":2,"command":"view.focus","args":{"ref":"demo/host/db-01"}}

Windows are numbered from 1 in the order they opened, as windows lists them. Naming a window that is not open fails, saying how many are. A client cannot open or close a window.

view shows the window named, and ask puts the question to the model in it: the model's moves happen there, and its answer shows in that window's narration panel. A client's steps show in the narration panel of the window they acted in.

What a client may do

A client reads only what the language model can: names, kinds, statuses, places and metrics already in the world. It never sees module options, credentials, the request log or who you are.

run takes the palette's commands except those that quit the app, name a file (place.export, place.import), type into the app (palette.open, filter.edit), or reach the language model or its request log (nl.ask, nl.explain, nl.panel, nl.log, ask.new), or show or change the license (license.show, license.add, license.remove), or open, close or link windows (window.new, window.close, window.follow). Naming a window gives a client nothing more: windows and view never show the license, even in a window with >license open.

Actions

action.run only proposes. The confirm panel opens, saying Proposed by control, and the answer says it waits:

{"ok":true,"result":"proposed restart on db-1; it runs only if the owner presses Y in the confirm panel"}

Nothing runs until you press Y, and N or Esc declines it. Only actions your config allows for that instance are offered (actions). The action log records control as who proposed it. A client cannot propose while you have the action panel open.

There is one confirm panel however many windows are open, and it shows in the window with the keyboard, where Y goes. Click another window and it moves there.

Seeing what a client did

Each step a client takes shows in the narration panel under control, such as focused db-02 or read the places, so you can always see who moved the view. While the language model is answering, the panel stays with its answer.

The app's log names each step's command or tool, never its arguments.

MCP

An AI agent that speaks MCP, the Model Context Protocol, can use Wayseer through wayseer mcp. The agent starts it and talks to it over standard input and output; it passes each request on to the control socket, so Wayseer must be running with control on.

Most MCP clients take a command to run. For Claude Code:

claude mcp add wayseer -- wayseer mcp

Clients configured by JSON, such as Claude Desktop or Cursor, take:

{"mcpServers": {"wayseer": {"command": "wayseer", "args": ["mcp"]}}}

Give the full path to wayseer if it is not on the client's PATH. On Windows it is wayseer.exe; on macOS, /Applications/Wayseer.app/Contents/MacOS/wayseer.

The agent is offered these tools:

search_entities
describe_entity
list_metrics
query_series
query_events
list_changes
list_flows
list_places
list_actions

Read what Wayseer shows, as the language model does.

navigate

Moves the view in one call: any of filter, window (a span such as 1h), until, focus, lens and place, in that order. place shows Geo there.

ask

Asks Wayseer's own language model a question.

propose_action

Opens the confirm panel on an action, which runs only if you press Y.

list_windows

Lists the open windows, as windows does.

Every tool but list_windows takes in_window, a window's number, to act in that window; it acts in the window used last without one.

Their descriptions come from the app's commands, so they match the palette. If Wayseer is not running, or control is off, wayseer mcp says so and exits with status 1; if it stops later, each tool call says so until it is back.

Limits

A request is at most 64 KB.
At most 16 requests are answered at once, across every client; another is answered busy, to try again.
A client that stops reading its answers for five seconds is disconnected.
A line that is not JSON, or names no known op, is answered with an error, and the connection stays open.