ValeDesk (NeuralDeskApp): A Tauri Desktop Agent That Points at Ollama, vLLM or LM Studio

What ValeDesk is, and who it is built for

ValeDesk is a desktop AI assistant that talks to any OpenAI-compatible endpoint. The README frames it as a framework rather than a product: "it's a framework you own," with the argument that the TypeScript and Tauri codebase is meant to be read and modified. The package.json description lists the same components: an OpenAI SDK compatible agent with a memory system, file operations, web search and a UI.

The intended user is a developer or researcher who already runs a model locally and wants a client that exposes the machinery. The README names three local serving options (vLLM, Ollama, LM Studio) alongside OpenAI itself, and suggests comparing Qwen, Llama and DeepSeek. If you only want a chat window over a hosted API, the tool surface here is larger than you need and the build requirements are heavier than installing a binary.

The repository carries files aimed at AI coding assistants themselves: CLAUDE.md, CURSOR.md, .claude/ and .cursor/ directories. That is a signal about how the project is maintained, and it also means parts of the documented behaviour live outside README.md.

How the agent loop is wired: OpenAI SDK, tools, sidecar

The architecture visible in the repository splits into a React frontend, a Tauri shell in src-tauri/, and agent code under src/agent/ that compiles to dist-electron/agent/main.js. The Makefile references a sidecar entry point at dist-sidecar/sidecar/main.js, and package.json exposes a transpile:sidecar script, so the agent logic can run as a separate process from the UI.

Tool calling is the core mechanism. The README lists tools under a snake_case verb_noun convention, including run_command, read_file and write_file, plus JavaScript (Node.js vm) and Python (system subprocess) sandboxes. The model returns function calls, the agent executes them, and the result goes back into the conversation. Two guardrails are described: a permission system with ask and default modes, and directory sandboxing for file operations.

State lives on disk. Sessions are SQLite-backed and survive restart, user preferences go to ~/.valera/memory.md, and every request and response is written as JSON per iteration under ~/.valera/logs/sessions/. That logging is the most useful part of the design for anyone debugging a local model: when a tool call goes wrong you can read the exact payload rather than guess. Loop detection fires on five or more sequential calls to the same tool, and LLM requests carry a five-minute timeout with auto-retry.

Installing ValeDesk and pointing it at a local model

The README lists Rust 1.74 or newer, Node.js 20 or newer, and Python 3 for the execute_python tool. The development path on macOS and Linux is a clone followed by npm install and make dev. The Makefile's ensure-node-deps target runs npm ci when node_modules is absent and then rebuilds better-sqlite3 for the current Node.js version, so the first make dev may take a while.

git clone https://github.com/vakovalskii/ValeDesk.git
cd ValeDesk
npm install
make dev

Start a local server before opening the app. The README gives the Ollama example directly: run ollama serve, then configure the base URL as http://localhost:11434/v1. For vLLM it shows a serve command with an explicit port.

ollama serve
# then in ValeDesk: http://localhost:11434/v1

vllm serve Qwen/Qwen2.5-14B-Instruct --port 8000
# then in ValeDesk: http://localhost:8000/v1

Configuration happens in the app, not in a file. Open Settings, then set API Key (dummy-key works for local servers), Base URL including the /v1 suffix, Model Name, and Temperature, which defaults to 0.3. The README's vLLM example shows the shape of those values.

{
  "apiKey": "dummy-key",
  "baseUrl": "http://localhost:8000/v1",
  "model": "qwen3-30b-a3b-instruct-2507"
}

After saving, send a message with Cmd+Enter or Ctrl+Enter. The token counter and API duration should populate once a response streams in. For voice input you first run the bundled setup script, which uses Docker by default and falls back to uvx or a venv.

chmod +x scripts/setup_voice_server.sh
./scripts/setup_voice_server.sh

The script accepts PORT, MODEL, DEVICE, COMPUTE_TYPE, DOCKER_TAG, DOCKER_MEMORY, DOCKER_CPUS and DOCKER_SHM_SIZE. In Settings, Voice, you then set Voice Base URL to something like http://localhost:8000/v1 and wait for the Connected indicator before using the mic button.

Where ValeDesk gets in your way

The build story is the first constraint. The README states Windows is coming soon and that a Windows build requires cross-compilation setup, pointing at .github/workflows/ for CI builds. If your team is on Windows, the documented path is to build from source through that setup, not to download an installer. The macOS packaging path is explicit: make bundle produces ValeDesk-0.0.8.dmg, and the manual steps use hdiutil against src-tauri/target/release/bundle/macos/ValeDesk.app.

The second constraint is the licence. package.json declares "license": "SEE LICENSE IN LICENSE", and the repository metadata reports NOASSERTION rather than a recognised identifier. The README badge says Community. That is not enough to tell you what you may do with the code, and it matters more here than in a library, because the agent executes shell commands and reads files on your machine.

The third is the sandboxing claim. The README describes directory sandboxing and a JavaScript vm, but it does not document what the Python tool's subprocess boundary actually restricts. Python execution is described as a system subprocess, which is a different isolation level from a vm. If you plan to let the agent run unattended, read the tool implementation before trusting the permission modes to contain it. The README also does not document rollback for file writes, so a write_file call that overwrites something is not recoverable through the app.

ValeDesk compared with a terminal coding agent

The closest alternative for the same job is a terminal-based coding agent such as Aider or OpenHands, which run in your shell and edit a working tree directly. The difference is not the model backend, since both drive OpenAI-compatible endpoints, but where the state and the interface live.

A terminal agent treats the repository as the workspace and the git diff as the review surface. ValeDesk treats the conversation as the workspace: sessions are SQLite rows, memory is a markdown file at ~/.valera/memory.md, and the interface is a React window with a todo panel, pinned sessions and a search field. That is friendlier for scheduled tasks and reminders, which the README lists, and for reading a rendered t.me channel with reactions and views, which a shell agent has no reason to do.

The trade-off runs the other way for code work. ValeDesk's file tools are the agent's own read_file and write_file rather than your editor's buffer, and nothing in the README describes a diff review step before a write lands. If your workflow depends on inspecting changes before they are applied, a terminal agent that stages edits in git gives you that checkpoint and ValeDesk, as documented, does not.

Maintenance, releases and what an upgrade costs you

The repository is not archived, and the last push was on 2026-05-15. That is roughly four months before today, so the codebase is not abandoned, but it is also not moving weekly. The release history is short and clustered: v0.0.5 on 2026-01-16, v0.0.7 on 2026-01-22, and v0.0.8 on 2026-01-26. No release has been tagged since January, which means the gap between the newest tag and the newest commit is where unreleased work sits.

Upgrade cost depends on how you install. If you build from source, moving to a newer commit means pulling, re-running npm install, and rebuilding the Tauri app and sidecar; the Makefile handles dependency checks but not migration of anything under ~/.valera/. If you use the DMG, you are pinned to a tag, and the README's manual hdiutil steps hardcode the version string in the volume name, so a new build means editing that command.

The licence question is unresolved in the repository. The LICENSE file exists at the repository root, but neither package.json nor the metadata states a standard identifier. Read that file before you redistribute anything, and note that the README badge labels the licence Community without defining it.

Editorial conclusion

Adopt ValeDesk if you already serve a model through Ollama, vLLM or LM Studio and you want a desktop client whose tool layer you can read and edit, with session logs in ~/.valera/logs/sessions/ for debugging. Do not adopt it if you need a signed Windows installer, a permissively licensed dependency set, or a packaged release you can hand to a non-technical colleague. Verify three things first: the contents of the LICENSE file, since package.json declares "SEE LICENSE IN LICENSE" rather than a standard identifier; whether the sandboxing described for file operations and the JavaScript vm matches the isolation your data requires; and whether a source build on your target platform succeeds, because the README marks Windows as coming soon and points at .github/workflows/ for CI builds.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. vakovalskii/NeuralDeskApp on GitHub