Install DeepSeek Harness on Ubuntu
Two steps, and neither of them installs anything into your system directories. Everything lives in your home folder and removing it is one command.
Point It at a Local Model, Not the Cloud
This is the part almost nothing else written about dsh covers. The built in providers are all paid cloud APIs, but the custom provider route will happily talk to Ollama on your own machine, and Ollama speaks the protocol dsh expects.
dsh does not serve models. It contains no model serving code at all, so it cannot download or run one. Something else has to be doing that, and on Ubuntu that something is usually Ollama. Our guide to installing Ollama on Ubuntu covers it in full.
You also need a model pulled and ready. This guide uses deepseek-r1:8b, a 5.2 GB download covered in our guide to installing DeepSeek on Ubuntu. Any model Ollama can run works the same way, including Llama.
If you would rather watch someone do this, the video below walks through the same job. It was recorded on an earlier release, so a few screens have moved since, but the idea and the settings are the ones above.
What DeepSeek Harness Actually Does
Before you send the first message, check which mode the agent is in. The picker sits at the top of the composer and the four modes give the model very different amounts of rope:
Standard is the right default. Minimal is worth knowing about for a local model: it reduces the agent to a persistent shell and a file editor, which means a far smaller system prompt and far less pressure on a context window that a small model does not have much of.
Make It Do More With Plugins
Plugins are not a side feature here, they are the design. A stock install already mounts well over a hundred of them, and you can see the lot under Settings, then Plugins, where each one can be switched off individually.
Installing a community plugin is one command. It adds the package to your web profile, which lives in ~/.dsh/profiles/web, and the shipped web profile reloads its configuration live, so there is nothing to restart:
Installing one runs somebody else’s program on your machine with your permissions. It can read your files, use your credentials and reach the network, and the approval prompts you see for the agent’s own tool calls do not sandbox plugin code. Being popular is not a security review. Read the source of anything you do not recognise, and try unfamiliar plugins somewhere that is not holding your keys.
Which DeepSeek Harness Plugins to Try
Each name below links to its repository, where you will find the exact package name to put after add in the command above. Star counts are from the time of writing and the ecosystem is young, so treat these as a starting point rather than a canon.
A plugin market inside the interface, so you can browse and install the rest without going back to the terminal. Install this one first and the others get easier.
Shows what is actually in the context window and how it is filling up. The most useful one on this list if you are running a local model, because a small model runs out of room long before a cloud one does.
Wraps the whole thing in a desktop application instead of a browser tab, which suits anyone who would rather not keep a tab open all day. The largest community project in the ecosystem.
Tracks and checks what is being published across the plugin ecosystem. Given the warning above, something that looks at plugins before you install them is worth having.
Puts the interface on your phone by scanning a code, while the model keeps running on the machine at home. A neat fit for a desktop with a graphics card in it.
Connects the agent to messaging apps, Telegram, Slack, Discord and others, so you can send it a job from wherever you are and read the answer later.
One warning about finding your own. The plugin topic on GitHub is being used by projects with no connection to dsh at all, because it is currently a popular tag. Sorting that page by stars puts image uploaders and database tools above real plugins, so read what a project actually does before installing it.
See Exactly What the Agent Did
An agent that edits files and runs commands is only worth trusting if you can check its work. Every session has a Trajectory tab next to the chat, and it lists each step in order: what the model was thinking, which tool it called, what it passed in and what came back.
Two habits are worth forming early. Read the trajectory the first few times rather than only the answer, because it is how you learn what your model does badly and where it wastes context. And keep the permission setting honest: the composer shows the current file policy next to the model name, and turning off approvals to stop the interruptions is exactly how an agent ends up rewriting something you needed.
Update It Without Losing Your Settings
Because the guide starts it with npx, there is no installed copy to upgrade, but npx will happily reuse a cached one. Ask for the latest release by name and you get it:
Your settings, credentials and sessions live in ~/.dsh, separately from the program, so they survive an update. Read the release notes before jumping between versions. This is preview software that warns about breaking changes, and the gap between the newest release and the one you were happily using can be a few days.
Fix the Common Problems
MISSING_CREDENTIAL, or no API key for provider: ollama
Ollama does not check API keys, but dsh insists there is one. If you set the provider up through the Models page, put any text in the credential field, such as local. If you wrote the YAML by hand with apiKeyEnv, then the named variable has to exist in the shell that starts dsh: export OLLAMA_API_KEY=local. Older releases word this error differently, so a message about no API key for the provider is the same problem.
UNKNOWN_MODEL
The model name has to match what Ollama reports exactly, including the tag. deepseek-r1 and deepseek-r1:8b are different strings as far as this is concerned. Run ollama list and copy the name from the first column, or use the Fetch available models button so nothing is typed at all.
The agent forgets what it was doing
Almost always the context window. Ollama defaults as low as 4,096 tokens, an agent uses that up quickly, and the overflow is dropped silently rather than reported. Start the server with OLLAMA_CONTEXT_LENGTH=40960 ollama serve and declare the same number in dsh. If you get token limit errors instead, the number is now higher than your hardware can hold, so bring it back down.
Nothing connects, but Ollama is definitely running
127.0.0.1 means the machine making the request, which is not always the machine you are looking at. If dsh runs in a container, in WSL or in a virtual machine, that address points back at itself, not at the Ollama on your desktop. Use the host’s real address instead. If you are running things in containers, our guide to installing Docker on Ubuntu covers how the networking fits together.
Every request fails, though the model and address are right
Some endpoints reject a request shape that OpenAI accepts. The two that account for most of it are the developer role, which is used for models that reason, and the field that caps output length. Add these to the provider in ~/.dsh/settings.yaml and try again:
compat:
supportsDeveloperRole: false
maxTokensField: max_tokensRemove It Cleanly
Nothing was installed system wide, so there is nothing to uninstall. Stop the server with Ctrl+C, then delete the directory it keeps its settings, credentials and sessions in:
mike@ubuntu:~$ rm -rf ~/.dshThat deletes your saved sessions and your stored API keys as well, so copy anything you want to keep out of it first. Your Ollama models are stored elsewhere and are not touched. If you installed the package globally rather than using npx, also run npm rm -g @deepseek-ai/dsh.
Frequently Asked Questions
Is DeepSeek Harness free?
The software is free and open source under the MIT licence. What can cost money is the model behind it, because the providers it ships with are paid cloud APIs. Point it at a model running locally in Ollama, as this guide does, and the whole setup costs nothing.
Does DeepSeek Harness replace Ollama?
No. It contains no model serving code, so it cannot download or run a model on its own. It sits above Ollama and coordinates the model Ollama is already running. You need both.
Do I need a DeepSeek API key to use it?
Not if you use a local model. A key is only needed for DeepSeek’s cloud service. Adding Ollama as a custom provider skips that entirely, although dsh still requires some text in the credential field even though Ollama ignores it.
Is it safe to install community plugins?
Treat a plugin the way you would treat any program you download. It runs with your permissions, it can read your files and reach the network, and the approval prompts for the agent’s tool calls do not sandbox it. Read the source of anything unfamiliar before installing it.
Is DeepSeek Harness ready for real work?
It is a developer preview and the maintainers say there will be compatibility breaking changes. It is stable enough to be useful and it is worth learning now, but keep backups, expect settings to move between releases, and do not build anything you cannot afford to rebuild.
One command starts it, one provider entry points it at a model on your own machine, and nothing you give it leaves the room.
Related guides: Install Ollama on Ubuntu · Install DeepSeek on Ubuntu · Install Llama on Ubuntu · Best Open Source AI Tools for Ubuntu
