Documentation
How to set up and use Darkstar.
Getting started
Darkstar runs on Windows 11. Run the installer and follow the pages. It asks for a license key. Leave it empty and you start the 31-day Community Trial. Then it offers a list of models to download. Take one, several or none. It installs for your account only, so there is no administrator prompt.
Open Darkstar from the Start menu or the desktop shortcut. Already have a model? Drop its .gguf file in the models folder inside the Darkstar folder, open Settings and pick it under Language Model. Then make a project and say something.
The window
Chat tabs run along the top, one per conversation. Your files, connected windows and projects are on the left. The message box is at the bottom, and below it on the right you see the speed of the current reply and how full the context is. The gear at the bottom left opens Settings.
| Sidebar | What it is |
|---|---|
| File Explorer | The project's files. Drag one into the message box to hand it to the model. |
| Application Interface | Connect a window from another program so the model can look at it and use it. |
| Projects | One per piece of work. Add Directory brings in a folder you already have. |
Settings has a column of buttons down its left side.
| Button | What it does |
|---|---|
| Save, Load | Keeps your whole setup as a workflow so you can come back to it. Ctrl+S saves. |
| Clear | Wipes the active chat's context. |
| Traces | Shows every tool call the model made, open instead of folded. |
| Internet Access | On, the browser tools work. Off, they don't. |
| Autosave Chats | Saves open chat tabs as you go. |
| Mute | Silences the interface sounds. |
| Theme | Cycles through Space, Light, Arctic and Terminal. |
The model itself is chosen under Language Model. Thinking is Reasoning Effort, under Text Generation.
Projects and chats
Everything lives in a project: a set of chats and one workspace folder, the place the model reads and writes. Choose that folder before you start, because Darkstar won't let you chat without one.
Delete a project and its chats go with it, along with the folder Darkstar made for it. A folder you attached yourself is only let go. Its files stay where they are.
Chatting
Type and send. Up and Down bring back what you sent before. Paste something huge and it folds into a chip instead of flooding the box. The full text is saved in the project's pasted folder.
Hover over a message for its actions: delete, edit, retry from here, continue a reply that stopped, copy the reply.
Slash commands
| Command | What it does |
|---|---|
| /compact [percent] [instruction] | Squeezes the oldest part of the chat into a summary so the model has room again. The default is the oldest 90 percent. Add an instruction to say what the summary must keep. |
| /continue | Picks up a reply that was cut off. |
| /adversary [x] [text] | Makes the model attack its own answer and then fix it. It does this x times. |
Language model
Settings, then Language Model.
| Setting | What it does |
|---|---|
| GGUF model | The model itself. Pick one from the list, or use ⋯ to find a file. |
| Projector | Optional. Lets a model that supports it see images. |
| Speculative drafter | Optional. A small model that guesses ahead so the big one can move faster. |
| Unload model | Frees the memory it was using. |
Inference
These decide how the model runs on your hardware. The defaults are sensible. Change one when you have a reason.
| Setting | What it does |
|---|---|
| llama.cpp backend | The engine. CUDA for NVIDIA cards, Vulkan for most others, CPU if you have no card. Get latest llama.cpp installs a newer build and keeps the old ones selectable. |
| Context size | How much the model can hold in mind at once, as a share of its maximum. Auto unless you say otherwise. |
| GPU layers | How much of the model sits on the graphics card. More is faster until the memory runs out. |
| KV cache | The model's short-term memory. Keep it in video memory for speed or in system memory for room. The K and V types set how it is stored. |
| Flash Attention | Cuts memory use on long contexts, on hardware that supports it. |
| CUDA devices | All your cards, only the idle ones, or ones you choose. |
| Multi-GPU loading | How a model is split across cards: one after another (the default) or side by side. |
| Threads, Batch size, Micro-batch size, Parallel Slots | Throughput tuning. Threads at 0 picks for you. |
| Multi-token prediction | For models that can guess several tokens ahead. |
Text generation
How adventurous the replies are. Reasoning Effort sets how long a model thinks before it answers, for models that think. Temperature, Top K, Top P, Min P and Repeat penalty are the usual dials: lower is steadier, higher is looser. DRY and Mirostat sit under Advanced sampling, and you can ignore them.
Conversation settings
System prompt is the standing instruction every chat starts with. Full chat context shows you everything the model is actually given.
| Setting | What it does |
|---|---|
| Name Conversations | Titles a new chat before its first answer. |
| Auto-compact | When the context reaches 90 percent, the oldest half is summarized for you. |
| Model idle unload | Frees the model after 10 minutes of silence. |
| Dynamic VRAM | Unloads the language model while an image is made, then brings it back. |
| Negative Prompt | Lets the model say what an image should not contain. |
| Maximum sub-agent depth | How many layers of sub-agents are allowed. 0 means no limit. |
| Allow sub-agents to spawn sub-agents | Lets a sub-agent start its own. |
Tools
Tools are how the model does things instead of only talking: read a file, run a command, open a page. Under Tools & Skills, Tool choice is Auto (the model decides), Disabled or Required, and Maximum tool rounds limits how many times the model can reach for a tool in one reply.
Built in
| Tool | What it does |
|---|---|
| read_file, write_file, patch, search_files | Read, write, change and search files in the workspace. |
| terminal, process | Run one command, or start, check and stop a background process. |
| spawn_subagent | Starts a temporary sub-agent with the same tools and rules, and returns its answer. |
| Application Interface tools | Click, type and read in a connected window. |
Included with Darkstar
| Tool | What it does |
|---|---|
| ask_user_yes_no | Asks you a short yes or no question. |
| browser_control | Browses the web and inspects pages. |
| file_search | Finds lines in a project's text files. |
| generate_image | Makes an image with the Image Model addon. |
| linux_terminal | Runs commands in a Linux shell. |
| list_dir | Lists a folder. |
| read_file_lines | Reads a range of lines from a file. |
| run_python | Runs Python code. |
| safe_edit_tool | Makes exact text edits that apply fully or not at all. |
| screenshot_html | Takes a screenshot of an HTML page from the workspace. |
| show_image | Shows an image in the reply. |
| threejs_inspection | Checks Three.js pages. |
| windows_cmd | Runs commands with Windows cmd.exe. |
| windows_diagnostics | Reads Windows diagnostics. |
Skills
A skill is a written guide the model follows for one kind of job. Darkstar ships with one, Procedural Motion & Sound, for animations, title sequences and music visualizers that run in a browser.
To add your own, open Tools & Skills, choose Add SKILL.md Files… or drag the files in. A skill is a Markdown file called SKILL.md that opens with a name and a description. Skills live in agent_assets/skills.
Writing a tool
A tool is one Python file. Add it with Add Tool Files… or drop it in agent_assets/tools. It imports the registry, describes itself and registers a function:
from tools.registry import registry
SCHEMA = {
"name": "my_tool",
"description": "What the tool does.",
"parameters": {"type": "object", "properties": {}},
}
def handler(args, **context):
return "result"
registry.register(
name="my_tool", toolset="custom", schema=SCHEMA,
handler=handler, description="What the tool does.",
permission={"risk": "read"},
)Addons
Addons add abilities. Add addon lists the ones Darkstar finds on your computer.
API Model
Use a model hosted by OpenAI, Anthropic, Qwen or any OpenAI-compatible service. Your messages go to that service, which makes this the one setting that sends your chat off your machine.
Image Model
Teaches the model to make images. Pick a diffusion model under Diffusion GGUF. Darkstar reads the file and works out what else it needs: text encoders, a VAE and so on. If exactly one matching file sits beside it, Darkstar picks that one. If there are several, the choice is yours. Use the ⋯ button.
DM Sampler
The image settings: seed, steps, guidance, sampler, scheduler, attention, denoise strength, and which device does the work. A seed of -1 is random. Steps and guidance at 0 let the model choose. The model can only make images once Image Model and DM Sampler are both set up. Finished pictures are saved as PNG.
MCP Servers
Connects MCP servers and hands their tools to the model. A server can run on your computer or sit behind HTTPS. Plain HTTP only works for localhost. Don't paste secrets into the settings. Write a variable such as ${API_KEY} in a header or environment value and Darkstar fills it in.
Workflows
Save workflow writes your current settings to a .dswf file in the workflows folder. Load workflow puts them back. Handy for flipping between setups, say one for chatting and one for coding.
Voice input
Hold the voice hotkey in the message box (Ctrl+O unless you changed it), talk, and let go. Your speech is turned into text on your computer and lands in the box. The microphone, the method and the hotkey are under Conversation in Settings.
Browser Workspace
Opens a web page or a local HTML file beside the chat, with back, forward, reload and an address bar. Choose local HTML opens a file from your computer. Restart online browser session starts the online browser clean. Back to chat closes it. Online pages need Internet Access on.
Trial and license
Your 31 days start the first time you open Darkstar. At startup a notice tells you how many are left and links to the plans.
Where Darkstar keeps things
Darkstar installs to %LOCALAPPDATA%\Programs\Darkstar unless you picked another folder. Your chats, projects and settings live in %LOCALAPPDATA%\Darkstar. Models sit in the models folder inside Darkstar's own. Uninstalling keeps your models and your data unless you tick the box to delete them.
Troubleshooting
| Problem | What to try |
|---|---|
| "Context contract exceeded" | The chat no longer fits. Raise the context size in Inference, run /compact, start a new chat, or delete old messages. |
| The model won't load | Pick the backend that matches your graphics card, or lower GPU layers or context size. |
| The model ignores its tools | Tool choice must not be Disabled. Browser tools also need Internet Access on. |
| The model won't make images | Set up Image Model and DM Sampler. The tool only appears when both are valid. |
| The model can't see an image | Choose a projector under Language Model. |