Assistant (voice and chat)#
Maystro's assistant answers in the chat panel and by voice, and can act on the
app: switch studios, set a prompt, start a generation. It runs a local language
model through llama.cpp's llama-server, a process Maystro starts and stops
itself. Nothing leaves your machine.
Models#
The assistant models are optional bundles on the Assistant tab of the Models area (top bar, Models):
| Bundle | Model | Size | Used for |
|---|---|---|---|
| Orchestrator | Qwen3 8B, Q4_K_M | 4.7 GB | voice commands, tool calls, short chat |
| Writer | Qwen3.8 27B, UD-Q3_K_XL, with its vision projector | 13.1 GB | long-form work: screenplays, prompts |
| Vision | Qwen3-VL 8B, Q8_0, with its projector | 8.8 GB | image to prompt: describes a picture for the prompt box or the Prompt Builder |
All three are Apache-2.0 open weights. The vision model is loaded only when
Image to Prompt or Fill from Image asks for it and keeps its projector on the GPU.
Image to prompt - default vision model on the same tab sets which model
those popovers start with (a catalogue model or one of your own GGUFs); a
model picked inside a popover stays until you pick another. The files land in the llm folder under
your models root. The orchestrator is enough for voice control and fits next
to the voice service on a 16 GB card; the writer needs the whole card and is
loaded only when a writer task asks for it. The model selector in the
assistant panel lets you answer chat with any served model, the writer
included, as long as the voice service is off. The writer also writes
screenplay packages from a brief
(Video Studio → Projects → Write screenplay from brief); any served GGUF
can take that role, and the writer runs with a 32k context for it.
Voice services#
Spoken replies and the wake word come from two small services next to the assistant (a text-to-speech voice and a wake-word listener). They are not included in this version: the voice chip beside the LLM chip on the assistant screen shows Voice services off, the Test voice button and the Wake word mode stay disabled, and the assistant answers in text. The typed chat and the microphone (Tap to talk) work without them. Where the services do run, the chip shows them as ready and its tooltip lists the address each one is on; they choose a free port when they start, so a port taken by another program or reserved by Windows never blocks them.
Voice input (the microphone on the assistant screen and the wake word) needs a local speech-recognition model: Whisper Large v3 Turbo installs from Models → Assistant → Speech recognition, is 1.6 GB and transcribes Turkish and English on the GPU. Without it the microphone stays off and the assistant screen says where to install one; the typed chat works regardless.
Your own GGUF#
Put any .gguf file in llm under a models root (the primary root or an
extra root) and press Rescan folder on the Assistant tab (or restart
Maystro); it appears in the served model list under its file name. A projector
file whose name starts with mmproj and shares the model's name
(mmproj-Qwen3.8-27B-BF16.gguf next to Qwen3.8-27B-UD-Q3_K_XL.gguf) is
picked up as its vision projector and the model gets a vision badge, which
also makes it selectable for Image to Prompt. A writer's projector is kept in
system memory so it costs no VRAM; a vision model (VL in its name) keeps its
projector on the GPU so images are encoded in a moment. A projector with a
generic name (mmproj-F16.gguf) next to several models pairs with none of
them by name: pick it from the projector selector on that model's row in
the served list. The mapping is remembered and the server restarts with it.
Add your own GGUF on the same tab fetches a file (and its projector)
straight from a public Hugging Face repo: enter the repo (owner/name), the
model file name and, optionally, the projector file name. The files land in
llm under names that pair them (<name>.gguf + mmproj-<name>.gguf); when
the download lines say done, rescan. Uncensored variants are not in the
catalogue on purpose; this is the way to use one. Weights you bring are covered
by their own license.
If the Vireo sidecar is not running when you download, the file goes to the
local llm folder of your Maystro root instead; that folder stays served once
the sidecar is up. A GGUF that is in a served folder but not served yet (a
finished download, a file you copied in) is listed on the server card as
Not served yet, with a Rescan folder button next to it.
How the writer fits the card#
A writer model is about 13 GB and has to share the card with the desktop and the Vireo sidecar. Before a writer job loads it, Maystro compares the memory the model needs (as llama.cpp itself projects it for the job's settings) plus a small margin with the card's free memory, and makes room in this order:
- the chat model and any other assistant model are unloaded;
- the image models of your last generation move from the card to RAM (the next generation takes them back within a second or so);
- if a video job has just finished, Vireo's warm pipeline is released (the next video job builds it again, which takes a few seconds);
- only if that is still not enough, the first layers of the model run on the CPU — the job still runs, more slowly (each layer on the CPU costs roughly 10–15 % of the writing speed).
The writer also runs with a single request slot: a writer job is one stream,
and each extra slot of a hybrid model such as Qwen3.8 27B reserves about 0.6 GB
at a 32k context. The result is shown in the writer window and on the model's
row on the Assistant tab, for example GPU 66/66 and 66/66 layers on the
GPU · needs 13.4 GB + 384 MB margin · 14.9 GB free. The margin is
agent_llm_vram_margin_mb in maystroai.yaml; a model you placed yourself in
agent_llm_model_presets (n-gpu-layers, n-cpu-moe, override-tensor)
is left as you set it.
While you render#
Before every render or training run the assistant model is unloaded so the whole GPU belongs to the job; the status chip in the assistant panel shows paused and chat answers that it is paused. When the queue is idle again the model is reloaded by itself — if it fits next to what the job left on the card.
After an image generation Maystro keeps the image models on the card for your next generation, and a vision or chat model often does not fit next to them. It then stays unloaded until you use it: the first request (a chat message, Image to Prompt, a caption) moves the image models to RAM and loads the assistant model on a free card. That first answer takes a few seconds longer (the model loads); the next ones are as fast as on an empty card. Without this step Windows would page part of the model to system memory and every answer would take many times longer (an Image to Prompt took 15 s instead of 1.5 s in our test). Your next generation takes the image models back from RAM. The chip's tooltip shows what happened, for example kept Qwen3-VL-8B-Instruct-Q8_0 unloaded: needs 9.3 GB, 5.5 GB free on the card or made room for Qwen3-VL-8B-Instruct-Q8_0 in 0.6 s (moved the image models to RAM).
The status chip#
The chip next to the model selector reads:
- LLM ready: a model is loaded and answering.
- LLM idle: the server is up; the first request loads the model.
- LLM paused: a render or a training run holds the GPU.
- No assistant model installed: install a bundle or add a GGUF.
- LLM server is not running: the
llama-servercomponent is missing or failed to start; hover the chip for the reason.
Hover the chip for the details: mode, llama-server path, models folder,
port, loaded models, last event. The Assistant tab of the Models area shows
the same details as a card, plus every GGUF the server serves with its size
and whether it is loaded.
What the assistant can do for you#
Besides navigating and pressing Generate, the assistant has server-side tools it can call on your behalf:
- Video Studio: list projects, open a project's scenes and shoots, create projects, scenes and shoots, list presets, list a shoot's takes, select a take, delete a take (one, or several of a shoot at once), queue a whole scene for generation.
- Gallery: list boards, create a board, list images (by board or search term), move images to a board or out of one, delete images.
- Image generation: list installed image models and LoRAs, and generate a Krea 2, FLUX.2 Klein, SDXL or Z-Image image from a prompt with explicit size, steps, seed, board and LoRAs; with FLUX.2 Klein, gallery images can be passed as references, so "make a portrait of the person in that image" works. Canvas work (image-to-image, inpainting, control layers, the SDXL refiner) still goes through the on-screen settings and Generate. The gallery's metadata recall restores the LoRAs and references it used. It can also give a Character Studio character to chosen people of a gallery picture ("put Mia on the woman on the right"): only their heads are regenerated, see Apply a character to a person.
- Queue: overall queue status or the status of one batch.
- Training Studio: list training projects with their datasets and runs, start a LoRA training run, check a run's progress.
Ask in plain language ("list my video projects", "generate a 768×768 image of a goose on a lake", "which take is selected in shoot 2?"); the assistant picks the tool, looks up ids itself and summarises the result.
Approval cards#
Actions that cost GPU time or cannot be undone (generating a scene or an image, applying a character to a person, starting a training run, deleting takes or images) are never executed on the assistant's say-so. The chat shows an approval card describing exactly what would happen (how many shoots, which model and size, how many steps) with Approve and Decline buttons. Nothing runs until you approve; declining, clearing the chat or waiting five minutes cancels the action and the assistant tells you so.
On the voice channel the card is read out, followed by "Do you approve? Say yes or no.", and the microphone opens for your answer: a spoken yes, approve, evet or tamam approves, no, cancel, hayır or vazgeç declines. What was heard appears in the transcript as your line and the card shows Approved by voice. If the answer is unclear the assistant asks once more, then leaves the card to the buttons, which stay live throughout.
The assistant's image model#
When you ask the assistant for an image it generates with Krea 2, FLUX.2 Klein, SDXL or Z-Image: the main model you pin here decides the architecture, and without a pin it is Krea 2 (or, without Krea 2, the first of the others that is installed). Without a pick Maystro guesses: the official Krea-2-Turbo installed from the catalogue first, then by name (a model saying official, then turbo), and Krea 2 Raw — the training base, not a generation model — only when nothing else is installed. Community merges you bring yourself carry no such mark, and in a library full of them the guess can land on a model that ignores your prompt. Choose the model under Models → Assistant → Assistant's image model. The line under the picker always says what would actually run and why: your pick, a guess, or a warning that the model you pinned is no longer installed. For SDXL and Z-Image the guess takes the official checkpoint when it is installed and otherwise goes by name, so pin the merge you want. You can still ask for another architecture in the request ("with FLUX.2", "with SDXL"). A single-file FLUX.2 Klein checkpoint needs its matching Qwen3 text encoder and the FLUX.2 VAE installed next to it; a single-file Z-Image checkpoint needs the Qwen3 4B text encoder and the FLUX.1 VAE (or a Diffusers Z-Image model to take them from). Steps and CFG the request does not name come from the model's default settings, otherwise from the architecture: Krea 2 8 steps, FLUX.2 Klein 4, SDXL 30 at CFG 7.5, Z-Image 9 — the distilled models run at CFG 1.
Image prompt rewrite#
The assistant writes the image prompt itself, in English, and the small orchestrator model is not a great translator (a kaz, a goose, once became a duck). Models → Assistant → Image prompt rewrite hands that step to a dedicated call before the approval card:
| Setting | What happens |
|---|---|
| Off (default) | The assistant's own prompt runs as-is. |
| Orchestrator model | A focused translate-and-tighten call on the small model; fast. |
| Writer model | The large writer model translates and tightens the prompt: the best translation, but it does not fit next to the voice services on a 16 GB card, so each rewrite is slow there. Best with the typed chat. |
With the rewrite on, the assistant passes your words along in your own language and the card shows both prompts, the one you gave and the rewritten one, with the model that wrote it. What the card shows is exactly what runs: the rewrite is kept for the approval, never redone behind it. If the model cannot answer, for instance while a render holds the GPU, the image is still offered on your original prompt and the card says why.
External harnesses (MCP)#
Advanced: the same server-side tools are also served over the Model Context
Protocol at http://127.0.0.1:9090/api/v1/agent/mcp (Streamable HTTP). Point
any MCP client at that URL with either your Maystro session token
(Authorization: Bearer <token>) or an API key created under Admin → API
keys (X-API-Key: msk_…); it gets exactly the tools and permissions your
account has. Actions that need approval return a preview first (with a
confirm_token) and run only when called again with confirm: true and that
token, so the harness can ask you in its own interface. A ready-made overlay for DeepSeek Harness (dsh) ships in the
repository as scripts/dsh/maystro-mcp.patch.yml: set MAYSTRO_API_KEY and
start dsh with --patch <that file>; the tools appear as mcp__maystro__….
A second, optional overlay, scripts/dsh/maystro-hooks.patch.yml, makes dsh
itself ask before Maystro's costly tools (generating, training, deleting); pass
it as another --patch. Its hook only prints a decision: on Windows dsh runs
hooks in a sandboxed PowerShell that cannot write outside the workspace, and a
hook that fails there lets the tool run.
Approval for external tools#
A harness that receives the preview also receives the token — and some answer that preview themselves rather than asking you (DeepSeek Harness does when run headless). So Maystro asks on its own side. Under Models → Assistant → Approval for external tools (MCP) you choose what happens when an external tool confirms a costly action:
| Setting | What happens |
|---|---|
| Ask me in Maystro (default) | The call waits on the server and a card appears wherever you are in the app. If Maystro is not the visible tab, the tab title shows Approval waiting, a short tone plays and, once you have pressed Allow browser notifications under the setting, a browser notification appears; the card itself is drawn when you return to the tab. Approve and it runs; decline and the harness is told you refused. No answer within the wait for an answer time (30 seconds to 10 minutes, 90 seconds by default; keep it under the harness's own tool timeout, 120 seconds for DeepSeek Harness) counts as a refusal. |
| Trust the harness | The call runs immediately — choose this only for a harness you are driving yourself. |
| Refuse costly actions | Generation, training and deletion from external tools are rejected outright; do them in Maystro. |
Reading, listing and searching are never gated — only the actions that cost GPU time or cannot be undone.
What the assistant did#
Every server-side tool call is written to logs/agent_tools.jsonl in your
Maystro root: when, which tool, who called it (you, or the API key a harness
used), whether it acted, previewed or failed, and how long it took. Prompts and
long lists are shortened and confirmation tokens are never written. It is the
record of what an external harness actually did on your machine.
The same log is shown in the app under Models → Assistant → What the assistant did: the most recent calls newest first, filterable by tool, with the outcome (ran, previewed, failed), the door the call came through (in-app, MCP, API key), who asked and how long it took. Click a line for the arguments.
External endpoint#
Advanced: set agent_llm_mode: external and agent_llm_base_url (plus
agent_llm_api_key if needed) in maystroai.yaml to use another
OpenAI-compatible server such as Ollama or LM Studio. Maystro then starts no
server of its own and does not pause the model for renders; keep that server
off the GPU while you generate.