Assistant

The Assistant turns obserae into a conversational investigation and operations interface. You describe the outcome you need in plain language; the model can inspect the product documentation, translate your question into NFQL, query the observed traffic, correlate the result with the cartography and threat feeds, and propose a change when the investigation calls for one.

“The NAS opened an SSH connection at 01:00. Is the destination IP in the threat feeds?”

This is more than a chat box placed on top of the application. Instead of writing the NFQL yourself, finding the NAS addresses in the cartography and cross-checking each destination in the enrichment tables, you state the question. The model can perform those steps in sequence, inspect the result of each one and adapt the next step. It then answers with evidence: the tools and queries it used remain visible, inspectable and re-runnable.

That combination is what makes the interface powerful:

• Natural language becomes a real investigation. The model does not have to guess from a static prompt; it can query the data available in your obserae instance.
• Several product areas can be correlated in one conversation. A single question can combine sessions, alerts, cartography, rules, documentation and enrichment.
• The result is actionable. The same conversation can move from observing a problem to proposing a cartography, flow-matrix, detection-rule or alert-status change.
• The operator stays in control. obserae filters the available tools using your permissions and applies your confirmation policy to every write.

The quality of that experience depends on the selected model. In particular, the model must support tool calling; a text-only chat model cannot perform the live queries and actions described on this page.

How a request is handled

It helps to picture one turn as a short, supervised workflow:

1. You ask a question or request an outcome.
2. The model receives only the tools allowed for your account.
3. It chooses a tool and supplies structured arguments — for example, an NFQL query and a time range.
4. obserae checks your permission again, runs the tool and returns the bounded result to the model.
5. The model may call another tool to refine or correlate the result, then writes its answer.
6. If a tool would change data, the turn pauses before execution and shows you the exact proposed action. Nothing is written until you approve it.

The model therefore plans the investigation, while obserae remains the only component that reads or changes application data. The model never receives database credentials or unrestricted access to the server.

During the turn, the conversation shows whether the model is thinking, running a named tool or writing its answer. Tool calls and their results become part of the thread, so you can verify how a conclusion was reached instead of accepting an unexplained answer.

Tools available to the model

A tool is a narrowly defined obserae capability with a name, a description, a structured input schema and a required permission. The model must explicitly select a tool; it cannot invent a broader capability or bypass the tool’s validation.

The tools currently cover:

Read tools run without a confirmation click, although requests to a paid hosted model can still consume billable tokens. Every write tool is considered invasive and is subject to the confirmation policy described below.

Why tool support is mandatory

An endpoint being OpenAI-compatible does not by itself mean that every model it serves supports tools. The selected model must be able to:

• receive tool definitions;
• return structured tool calls with valid JSON arguments;
• read a tool result and continue the same turn;
• reliably choose a tool instead of answering from guesswork.

Without those abilities, the provider may answer ordinary chat prompts but the Assistant cannot reliably inspect live data or perform actions. Typical symptoms are an answer written entirely from assumptions, prose that says what query you could run instead of running it, malformed tool arguments, or a turn that makes no progress. Select a tool-capable model first; if a small local model still struggles, increase its context window or move to a stronger model.

Permissions and safety boundaries

The rules are enforced by obserae, not by the model’s good behaviour.

Using the Assistant grants no extra product access. The assistant:use permission lets you open the page and converse, but every tool also requires the corresponding product permission. The tool list sent to the model is filtered for your account, and the permission is checked again when the tool runs. If you cannot read alerts or edit the cartography in the GUI, the Assistant cannot do it for you either.

Documentation search only needs assistant:use. If a required permission is missing, the corresponding tool is not offered to the model; an attempted call is also refused at execution time. Granting assistant:use alone therefore creates a documentation-capable conversational interface, not a shortcut around RBAC.

Writes require explicit operator authorisation. By default, anything that writes stops and shows you a confirmation card with the exact change, which you Apply or Reject. You can deliberately authorise one named tool for the rest of the current conversation by ticking auto-approve for this conversation. Later calls to that tool can then run without another click. That authorisation never applies to another tool or conversation, and is cleared when you switch model.

Four areas are off limits, permanently:

Ask about one of these and the Assistant will tell you where the page is and what to click. It has no tool to do it for you.

Before the first conversation

Two permissions serve different purposes:

• assistant:manage lets an administrator configure model providers, API keys, pricing and budgets under Settings → AI Providers.
• assistant:use lets a user open Assistant. It does not grant access to sessions, alerts, rules or the cartography; those remain controlled by their own permissions.

At least one provider and one tool-capable model must be available. Once an administrator has configured them, open Assistant, choose the provider and model, and send a first question. Include the asset, time range and expected outcome when they matter; for example:

“Between 00:45 and 01:15 today, show the external SSH destinations contacted by the NAS, check them against the threat feeds, and explain any match.”

You can then ask follow-up questions without repeating the context, inspect or re-run the generated queries, approve or reject proposed writes, stop a turn that is going in the wrong direction, and export the complete investigation as Markdown or JSON.

Connecting a provider

Go to Settings → AI Providers and click + New provider. You need the assistant:manage permission; administrators have it by default.

Ollama — a fully sovereign Assistant

A locally hosted model is the natural choice when prompts and investigation results must remain under your sole control. With obserae, the model runtime and the model weights hosted on infrastructure you control — and no external proxy or fallback configured — the complete Assistant workflow is sovereign: questions, conversation history sent as context, tool arguments, tool results and generated answers do not need to leave your network. No third-party LLM service receives your traffic metadata, cartography or investigation details.

This makes the local-model option especially valuable in this application, where tool results can contain sensitive internal addresses, host names, communications and detection findings. There is no per-token provider charge; you retain control of the hardware capacity, model version, availability and energy cost.

Install Ollama, pull a model that supports tool calling (ollama pull qwen3:8b is a reasonable starting point), and add a provider:

That last box matters. obserae normally refuses to send requests to addresses on your own network — it is the guard that stops a misconfigured URL from turning the daemon into a probe of your internal estate. A local Ollama is a private address, so this provider needs the exemption. It applies to this provider only; every hosted service stays guarded.

Smaller models need less memory and compute, but are often weaker at deciding which tool to call, producing valid arguments and reasoning across several tool results. If the Assistant answers in prose where you expected it to run a query, try a larger tool-capable model before concluding the feature is broken.

Give Ollama a real context window. This is the single most common cause of an Assistant that “says nothing” on a local model. Ollama defaults to 4096 tokens, and the Assistant’s brief plus its tool descriptions already take roughly 2500 of them — leaving a model barely enough room to think and none to answer. Ollama ignores any window sent with the request, so it can only be set on the server:

# systemd: /etc/systemd/system/ollama.service.d/override.conf
[Service]
Environment="OLLAMA_CONTEXT_LENGTH=16384"

then systemctl daemon-reload && systemctl restart ollama. Check what a loaded model actually got with curl http://<host>:11434/api/ps — the context_length field is the truth, whatever the Modelfile says.

Thinking models are supported. A model that reasons before answering (gemma, the -thinking variants) streams its scratchpad first; the Assistant shows it live under Show reasoning in the waiting card, then replaces it with the answer. The reasoning is never stored and never sent back — it is a view of the work, not part of the conversation.

OpenRouter — one key, many models

Create a key at openrouter.ai, then:

OpenRouter publishes its prices, so Test fills the cost table for you and the Assistant can show you what each answer cost.

DeepSeek

DeepSeek does not publish prices through its API, so obserae ships an indicative table you can correct on the provider’s Pricing panel. A figure you type is never overwritten by a later refresh.

With either hosted provider, the prompt, the conversation context needed for the turn and any tool results selected by the Assistant are sent to that service. Choose a hosted provider only when this data flow matches your security and data governance requirements. Use a local provider for a fully sovereign deployment.

The endpoint field

For OpenRouter and DeepSeek there is nothing to decide: the field shows the service’s own address, greyed out. Tick Override the default endpoint only if you route through a proxy or a compatible gateway. Ollama works the same way, starting from http://localhost:11434/v1 — tick the box when your Ollama runs on another machine.

After saving

obserae goes and fetches the model list by itself: when you save a provider, when the daemon starts, and every six hours after that. You do not have to remember to check. The Default model field is a list of what the provider actually offers, and the Refresh button next to it asks again right away — useful the day a provider adds a model you want.

A brand-new provider has no list yet, because the key it needs was only just stored. The form stays open after saving, with the list filled in, so you can pick a default without reopening it.

Set a Default model so people opening a conversation do not have to choose. Test still exists and does the same round trip, plus recording whether the endpoint answered; a failed test shows the provider’s own error message, most often a mistyped key or a private endpoint without the exemption ticked.

If a provider is unreachable when you open a list, obserae shows the last catalogue it knew about and says so, rather than showing you nothing.

Choosing and configuring a model

There is no single best model for every obserae deployment. Evaluate candidates in this order:

1. Tool support: mandatory. Check the model’s own documentation, then test it with a question that requires a visible NFQL call.
2. Context window: the system brief, tool definitions, conversation and tool results must all fit. A nominally capable model with too little context can appear broken.
3. Tool-use quality: stronger models are generally better at selecting the right tool, composing valid NFQL and combining several results without losing the original question.
4. Data location: a hosted model sends the working context outside obserae; a local model keeps the entire LLM exchange on infrastructure you control.
5. Latency, capacity and cost: a larger local model needs more RAM or VRAM; a hosted model trades local capacity for token charges and network dependency.

After saving the provider, select a Default model for predictable behaviour across new conversations. Users can choose another advertised model before their first message. The provider and model are then pinned for that conversation so its history is not silently reinterpreted by a different model.

Advanced settings

Behind Show advanced settings in the provider form sit nine bounds. Every one of them is optional: leave a field empty and it shows what it inherits as a grey placeholder, so an empty box always means “inherit” and never “zero”. A figure outside the accepted range is refused when you save, with the range in the message — it is never quietly rounded to something else.

The context window deserves a word. For OpenRouter, leave it empty: obserae reads the real figure per model from the catalogue. For DeepSeek and Ollama the provider publishes nothing, so a family default is used — and for Ollama that default is 4096 tokens, because that is what Ollama serves whatever the model claims. If you raised OLLAMA_CONTEXT_LENGTH on your runtime, type the same figure here: obserae cannot ask for it over the API, and a window set too low compresses conversations sooner than needed, while one set too high lets the runtime silently drop the beginning of your prompt.

About your API key

The key is encrypted before it is written to disk, with the same mechanism that protects your alert-output credentials and device passwords. It is never sent back to the browser: once saved, the page shows only the first four characters so you can tell two keys apart. Editing a provider and leaving the key field blank keeps the stored one.

If you rotate obserae’s master key, the provider keys are re-encrypted with everything else — nothing to do on your side.

Costs

Every answer shows what it consumed: prompt tokens, completion tokens, and the cost when the model has a known price. A model with no price shows the token counts and no figure — obserae would rather tell you it does not know than print a confident $0.00. Ollama has no per-token provider charge, so obserae records its conversations at zero cost; the compute infrastructure remains yours to operate.

Asking it to change something

Read tools run immediately. A write that is not already auto-approved for this tool and conversation stops and shows you a card with the exact change before it happens:

Confirm action — flow_matrix_add_rule Allow host:nas → host:backup over 22/TCP, as rule “nas-to-backup”.

{ "name": "nas-to-backup", "src": "host:nas", "dst": "host:backup",
  "dst_service": "22/TCP", "protocol": "TCP" }

☐ Auto-approve flow_matrix_add_rule for this conversation [ Reject ] [ Apply ]

Reject performs nothing and tells the assistant so, which usually makes it propose something else rather than ask again. Apply runs it and the card turns green with what actually happened.

The auto-approve box applies to that one tool, in that one conversation. It never carries into another conversation, and it is cleared if you switch model. Everything the assistant does is recorded in the audit log either way — ticking the box removes the click, not the record.

What it can change

And only if you could do it. If your account cannot edit the cartography, the assistant cannot either while talking to you — it will say so rather than fail quietly.

Two things worth knowing

A rule that does not compile is quarantined, not live. obserae stores it so you can fix it, but it matches nothing. When that happens the assistant tells you plainly instead of reporting success — otherwise you would only find out the day the rule failed to fire.

Someone editing the cartography blocks it. The map allows one editor at a time. If a colleague has it open, the assistant reports who and does nothing. Close the editor and ask again.

Three things to try

“The NAS opened an SSH connection at 01:00 — is the destination in the threat feeds?” It looks the NAS up on your map to get its address, queries the sessions in that window, then checks each destination against every enrichment feed. You see each query it ran.

“Add backup.example.com to the cartography and let the NAS reach it over SSH.” Two confirmation cards: one for the host, one for the flow-matrix rule. Reject either and nothing from it is applied.

“Add a rule detecting NAS connections to the outside other than 22/TCP.” It writes the NFQL, runs it to see what it returns today, then offers to save it as a detection rule with a threshold and a schedule.

Working in a conversation

The provider and model pickers at the top remain available until you send the first message, then become read-only. The model list comes from the provider’s own catalogue, and its first entry names the provider’s default explicitly — you can see what “default” resolves to rather than take it on trust.

If the provider you pick has no default model and you choose none, Send stays disabled and says so. Nothing is sent, no conversation is created, and your message stays in the box.

While a turn runs, the thread shows what it is doing — thinking, running a named tool, writing the answer — so a model that takes its time is never mistaken for one that has stopped.

Enter sends the message; Shift+Enter starts a new line inside it.

The context meter

Every model has a context window: the amount of text it can hold in mind for one question. Everything counts towards it — the brief that tells the Assistant what obserae is, your questions, its answers, and the results of every tool it ran. When a conversation grows past the window, the model stops seeing the beginning of it.

The strip at the top of the conversation shows exactly that. Each bar is one message, drawn to scale against the window; the darker block at the end is the room held back for the answer, and the empty space after it is what is actually free. Hover a bar to see what it is and what it costs.

Under it you get the figures: 24.6k / 200.0k tokens, then how much is reserved and how much is free. A ~ in front of the numbers means no answer has come back with a token count yet, so they are an estimate from the text length. Once the provider reports its first count, the tilde disappears and the meter recalibrates itself against the real figure.

The outline turns amber as you approach the threshold, and red if the conversation no longer fits.

Compressing the conversation

Compress asks the model to summarise the oldest part of the conversation into a short factual note — what you asked, what was found, what was changed, what is still open — and then sends that note instead of those messages.

Nothing disappears from your screen. The thread you are reading, and both exports, keep every message exactly as they were. Only what is sent to the model gets shorter, which is what buys room for the next question.

If your administrator left auto-compact on, this happens by itself once the conversation approaches the threshold: you will see a short notice saying how many messages were folded in, and the meter drops. Compression costs one small request to the provider, so it appears in your usage like any other turn.

One thing it will not do: it never cuts in the middle of a tool call and its result, so it may reply that there is nothing old enough to summarise yet.

Stopping a turn

While a turn is running, a Stop button sits beside Send. Use it when the model has clearly gone the wrong way, or when a long answer is no longer worth waiting for.

Stopping is not the same as closing the tab. The turn runs on the server, so leaving the page only stops you watching it — the model keeps going, and keeps costing. Stop actually ends it.

Whatever the assistant had already written is kept, followed by a line saying you stopped it, so a half-finished answer is still yours to read and export. The conversation is immediately usable again: just ask the next question. One thing Stop does not interrupt is a tool that is already running — a change in flight finishes rather than being left half-applied, so the stop lands once it returns.

Exporting a conversation

When the assistant has produced something worth keeping — an investigation write-up, a list of hosts, an explained query — the header carries Export .md and Export .json.

.md is the report: the provider and model that produced it, when it was exported and what it cost, then the exchange in order, with each tool the assistant ran and what it returned. It is meant to be pasted into a ticket, a mail or a post-mortem. Long tool outputs are shortened there to keep it readable.

.json is the faithful copy: the same conversation with nothing trimmed, including the full tool arguments and results. Use it to archive a thread or to process it elsewhere.

Both download as files named after the conversation and the moment you exported it, so a folder of exports stays sortable. You can only export your own conversations.

When it says no

Ask it to change your retention policy, add a user, or read the audit log and it will tell you where the page is and what to click. That is not the model being cautious: those tools do not exist. The boundary is enforced by the software and verified by a test that fails the build if anyone ever adds one.

The same applies to anything it reads. Hostnames, documentation fields and threat-feed descriptions are written by third parties, and the assistant is instructed to treat them as observation rather than instruction. That instruction is not a guarantee — the guarantee is that even a completely misled assistant can only do what you could do, and only after you click Apply.

Limits

A conversation has no length limit. Keep the same thread for as long as it is useful: nothing seals it, nothing trims it, and compression keeps it affordable by summarising the oldest turns as you go. One turn makes about 8 tool calls and lasts at most 5 minutes. “About”, because the Assistant often asks for several tools in one go and always finishes the batch it started rather than leaving half of it unanswered; the turn then ends with a line saying the budget is spent, and you continue by asking again. Conversations are private to you and are kept until you delete them — nothing expires them on a timer, and opening a new one never costs you an old one. If you go over your monthly budget, the next message is refused before any request is sent, so it costs nothing. A turn you stop may show no cost at all if the provider had not yet reported what it had used — the figures then shown are estimated from the length of the text, marked with a ~, and deliberately not billed against your budget.

The endpoints you configured and the monthly ceilings an administrator set both travel in the configuration bundle, under llm: and assistant: — so a restore brings back a working Assistant instead of an empty provider list. Your conversations and your recorded spending stay where they are: they are data, not configuration. An API key rides encrypted with the instance master key, which means it comes back working on the same instance and has to be re-entered on a different one.

Where to go next