DS4Server/docs/USER_GUIDE.md

DS4Server User Guide

DS4Server is a native macOS application for running supported DwarfStar models locally. Model files, chats, project references, settings, checkpoints, and agent-extension data stay on this Mac.

Getting started

1. Open View > Model Manager (⇧⌘M). Download a supported model and any acceleration artifact you intend to use, or verify an artifact already on disk. A model cannot run until its complete file passes verification.
2. Choose Add project and select the folder the agent should work in. The project remains in its original location; DS4Server stores only its reference and chat data.
3. Choose File > New Chat (⌘N). Select a thinking profile and a shell permission mode in the composer.
4. Enter a request and send it. The choices match the selected model: DeepSeek offers Direct, Think Low, Think High, and Think Max; GLM 5.2 offers Direct, Think High, and Think Max; GLM 5.3 Flash always thinks and offers Think Low, Think High, and Think Max.

The selected model is shared by the app and the optional local HTTP endpoint. Preferences are saved locally and generation settings are scoped by model and thinking profile where the controls indicate that.

Projects, chats, and context

The sidebar switches projects and chats. Project controls add, rename, or delete a project reference. Deleting one removes its DS4Server sessions and checkpoints, but never deletes the referenced folder. An unsaved draft can move to another project; a saved chat remains attached to its original project.

Chat controls can rename, pin, archive, restore, compact, rebuild, export, or delete a conversation. Archived chats remain under the project's archive until restored or deleted. Deleting a chat permanently removes its transcript and KV checkpoint. File > Export Chat as Markdown (⇧⌘S) or Export Chat as HTML saves the visible conversation, including clearly labeled user, assistant, thinking, embedded content, and tool sections while excluding internal system messages. Markdown keeps embedded content as source code; HTML renders validated SVG figures and A2UI surfaces inline in a self-contained dark document. Tool-call JSON is collapsed by default and can be expanded from its disclosure row.

Send another prompt while a response is active to queue it for that chat. Stop cancels current model and agent work. You can work in several chats at once: each keeps its own transcript, prompt queue, tools, approvals, context, and interactive surfaces. Independent tool work may overlap, but model inference is serialized through one shared runtime so weights are not duplicated. Quitting with active chats asks whether to stop them first.

The context indicator shows used and available tokens. Near the limit, DS4Server compacts older model context while retaining the full visible transcript. Saved chats also keep local KV checkpoints for fast continuation. A checkpoint belongs to the exact model, quantization, context size, and runtime configuration that created it. After one of those changes, DS4Server reports a context rebuild, prefills the saved transcript, and writes a compatible replacement without losing messages. Rebuild context on next use requests the same safe rebuild manually.

Agent capabilities and safety

The coding agent can use native tools to list a directory, read files, search file contents, write or edit files, inspect Git state, and maintain Dev Brain. It can also run shell commands and use web search or visit pages when the task needs them. The native glob tool finds files recursively by basename or relative path pattern without a shell; content matching remains the search tool's job, and a directory listing remains a non-recursive view of one folder.

Tool calls are checked against typed schemas before execution. Unknown tools, missing or extra fields, malformed calls, and invalid values return structured errors instead of running. Results appear in the transcript. Copy actions expose their complete text, and large output may also be saved to a local file rather than filling the transcript. Stop cancels active generation and cancellable tool work.

The shell permission mode is stored with each chat:

• Heuristic applies DS4Server's built-in command-risk checks.
• AI based asks the local model to classify a shell command in a separate one-shot request. A risky result shows its reason. If classification fails or is invalid, approval is required.

An approval dialog shows the command and working directory. Allow once runs that operation; Deny returns the refusal to the agent. Destructive, network, privileged, application-control, credential, and outside-trusted-path commands require approval as applicable. Dev Brain's configured vault is trusted like the project for ordinary path checks, but does not bypass those risk classes.

Ralph loops

Ask the agent to use a Ralph loop when a bounded task benefits from repeated autonomous passes, for example, “Use a Ralph loop with at most 12 rounds to fix and verify this parser.” Ralph is an agent tool, not a view or slash command. Its default is 8 rounds and its allowed range is 1–64.

Each round receives the same objective in a fresh model context, inspects the current project, and leaves file changes on disk. The next round receives only the previous validated report, applicable workspace instructions, and available skills. The current model settings and permission mode still apply. Ralph stops on completion, a reported blocker, a failed round, cancellation, or the round limit; a worker's completion report is evidence to review, not independent certification. Ralph workers cannot start nested Ralph loops.

Workspace instructions and standard skills

DS4Server reads global instructions from ~/Library/Application Support/de.rfc1437.ds4server/AGENTS.md, then project instructions from root to the working directory. In each directory, AGENTS.local.md overlays AGENTS.md. Deeper guidance wins over broader guidance, while system, developer, and direct user instructions remain higher priority. Additions, changes, and removals are tracked during a chat and restored after compaction; an unreadable changed file leaves its last readable version in effect with a notice.

Manually installed standard skills live at ~/.agents/skills/<name>/SKILL.md. DS4Server initially gives the agent each valid skill's name, description, and location; the agent reads the full skill only when the task matches. These roots are readable but not writable through agent file tools. Start a fresh chat after changing the manually installed skill set so its prompt and tool roots agree.

Dev Brain

Dev Brain is a project-backed Obsidian wiki for durable, source-cited engineering knowledge. In Preferences > Dev Brain, select an existing vault containing .obsidian, enable it, and save. Ask the agent to build, refresh, search, or validate the wiki. DS4Server manages its contract files and explicitly marked topic pages, not Obsidian settings, hidden files, attachments, or unrelated notes. Verified pages can support answers; stale or needs-review pages are leads that the agent must recheck against project source. Disabling Dev Brain removes its tools and guidance without deleting the vault.

Agent extensions

Preferences > Agent Extensions installs and manages portable Codex plugins:

1. Enter an HTTPS Git repository URL and, optionally, a branch, tag, or commit.
2. Choose Install. The repository must contain .codex-plugin/plugin.json and provide at least a skills directory or a supported lifecycle-hooks manifest.
3. Inspect the displayed description, source URL, requested ref, resolved commit, author, version, skill count, and hook names.
4. Enable the extension. An extension with command hooks first asks for explicit trust. Its programs run with your user permissions even though DS4Server invokes them without a shell and limits their environment, runtime, input, and output.
5. Use Update to fetch the configured source/ref, disable the toggle to stop future use, or Uninstall to remove the installed package and its stored extension data. Hook failures appear on the extension row.

Enable, disable, and update changes apply to subsequent matching hook events. A current chat does not retroactively receive a SessionStart event. Because a chat's native tool roots are initialized for that session, start a fresh chat after adding, updating, enabling, or disabling extension skills. An app restart is not otherwise required.

Extension skills are versioned inside their plugin and are managed with its toggle, update, and uninstall actions. They are separate from manually installed standard skills under ~/.agents/skills. Installed packages, per-extension data, and registry.json live under ~/Library/Application Support/de.rfc1437.ds4server/extensions/.

A2UI interactive surfaces

A2UI is an interactive or graphical response the agent can generate when it is more useful than prose. It is not another model and is not a tool you operate directly. Enable or disable it in Preferences. Ask for an interactive chart, table, form, map, or other surface, then open the A2UI view (⌘2) if the app does not switch there automatically.

Buttons can send events back to the agent. Text fields, checkboxes, sliders, date/time inputs, and choice pickers update the surface's data. Tabs and modals organize content. Previous and next actions navigate saved surface history; Dismiss removes the current saved surface after confirmation. Ordinary model prose remains in the Chat transcript. Video and audio controls open native playback windows.

The embedded catalog currently supports:

• Content: Markdown/text, images and avatars, icons, video, audio, and dividers.
• Layout: rows, columns, lists, cards, modals, and tabs.
• Controls: buttons, text fields, checkboxes, sliders, date/time inputs, and single- or multiple-choice pickers.
• Visual and research components: bar, line, area, stacked-bar, pie, donut, and heatmap charts; tables; metrics; timelines; maps; mind maps; and forms.

The rest of the app

Models and preferences

Model Manager downloads, resumes, verifies, and removes managed model and acceleration artifacts. Removing an artifact does not remove projects or chats. Preferences select the active model and its default thinking profile. Generation values are stored per model and thinking mode; acceleration and SSD settings are stored per model; the custom system prompt is shared across profiles. Other sections control A2UI, permission defaults, endpoint settings, Git diff display, Dev Brain, extensions, checkpoint storage, and diagnostics.

A new draft uses the currently selected model when its first turn is persisted. From then on the session keeps that exact model, so opening it immediately selects the same model and that model's thinking choices. Legacy sessions recover the exact model from their checkpoint when available; a legacy session whose exact model can no longer be identified remains viewable but cannot be continued.

Main views, sidebar, and branches

Chat shows the conversation, A2UI shows interactive surfaces, Git shows the current worktree, and Stats reports model, generation, HTTP, SSD, and KV-cache activity. View > Show Sidebar (⌘B) hides or restores the project sidebar. The composer status shows the active project and its local Git branch. Branch switching is available while that project's chats are idle.

Git

The Git view separates staged and worktree changes. Select files to stage, unstage, or commit; selecting a file opens a colored unified or side-by-side diff. Committing with no selected or staged files asks before staging and committing every change. Fetch, pull, and push use the origin remote and report authentication, hook, conflict, and other Git errors.

Local API

Preferences can enable an OpenAI- and Anthropic-compatible endpoint on 127.0.0.1, port 4000 by default. Endpoint conversations belong to their client and do not appear in the sidebar. CORS is off by default; enable it only for trusted browser clients on this Mac. Saving changed endpoint settings restarts the local listener.

reasoning_effort accepts only the selected model's advertised values from GET /v1/models: DeepSeek accepts none, low, high, or max; GLM 5.2 accepts none, high, or max; GLM 5.3 Flash accepts low, high, or max. Omitting it uses the upstream model default: low for DeepSeek and max for both GLM models. Unsupported values and conflicting thinking controls return a 400 error instead of being converted to another effort. This per-model thinking selection is intentionally part of the DS4Server agent harness, not a DS4 parity surface; do not replace it with mapped, hidden, or shared choices.

Data and recovery

Application data is under ~/Library/Application Support/de.rfc1437.ds4server/: config.yaml stores preferences, data.sqlite3 stores projects and chats, models/ stores managed artifacts, kv-cache/ stores checkpoints and metrics data, extensions/ stores plugins, and browser/ stores the agent browser profile. Project source remains where you selected it.

Removing a model can be recovered by downloading or restoring and verifying the same artifact. A context incompatible with changed runtime settings is rebuilt from the saved transcript. Deleted project references, chats, extension data, and their checkpoints are not restored by DS4Server; use your own backup if you need recovery from deletion.

Troubleshooting

• No model selected or model unavailable: select a model in Preferences, then download and verify all required artifacts in Model Manager.
• Verification failed: retry verification or download. DS4Server will not load incomplete or hash-mismatched weights.
• Context is rebuilding: the saved checkpoint no longer matches current model/runtime settings. Let the transcript prefill finish; messages remain.
• Extension install failed: use an HTTPS Git URL and verify the repository contains a valid portable plugin manifest plus skills or supported hooks.
• Extension hook failed: read the error on its Preferences row, repair or update the extension, then retry the matching event. Trust is required before command hooks can run.
• Tool approval denied: the operation was not run. Send a safer request or repeat it and approve only after checking the command and working directory.
• A2UI is unavailable: enable A2UI in Preferences and ask the agent for an interactive surface in a new prompt.

Keyboard shortcuts

These are the shortcuts registered by the native DS4Server menu. On Macs whose top row controls brightness or media, use fn-F1 when macOS requires it; DS4Server does not override the system keyboard mapping.

Shortcut	Action
F1	DS4Server User Guide
⌘,	Preferences
⇧⌘M	Model Manager
⌘N	New Chat
⇧⌘S	Export Chat as Markdown
⌘B	Show or hide the sidebar
⌘1	Chat view
⌘2	A2UI view
⌘3	Git view
⌘4	Stats view
⌘Z	Undo
⇧⌘Z	Redo
⌘X	Cut
⌘C	Copy
⌘V	Paste
⌘A	Select All
⌘Q	Quit DS4Server