DeepSeek use Guide: Run Your First Agent

You can call DeepSeek’s API all day and still not have a coding agent. You get text. No workspace awareness, no shell loop, no approval gates, no replayable run history. That’s the gap DeepSeek use just tried to close – and the release is loud right now because DeepSeek open-sourced the runtime layer itself, not another closed IDE chat pane.

As of mid-August 2026, DeepSeek use (dsh) v0.1 ships as a developer preview under MIT. On the official use page the line is blunt: agent = model + use. Models think. The use is what lets them touch files, run tools, keep sessions, and stay inspectable.

One naming mess first. Search results still mix in third-party tools people nicknamed “DeepSeek use” months ago. This tutorial is only about the official package: @deepseek-ai/dsh from deepseek-ai/deepseek-use.

Why raw models and closed agents fall short

Hitting the DeepSeek API directly is fine for single-shot answers. It falls apart the moment you need multi-step work: read the repo, edit three files, run tests, recover from a failed command, then explain what changed. You end up hand-rolling tool schemas, state, and retries.

Closed coding agents fix that path – until you want to swap the model backend, replace the sandbox, or audit every token the model saw. Then you’re stuck. DeepSeek’s answer is a Cordis-powered kernel: models, tools, skills, sessions, sandboxes, storage, loops, scheduling, and even the UI are plugins you recompose in config instead of forking a monolith. The design notes live in the Cordis paper A Programming model for Spatiotemporal Composability.

Honest tradeoff: this is not a polished Claude Code clone with desktop apps and hosted background agents. VentureBeat’s launch write-up frames it as open agent infrastructure still in preview – useful, unfinished, and worth treating like early software.

Launch DeepSeek use in one command

You need a current Node.js install. From the project folder you care about:

npx @deepseek-ai/dsh web

That starts the local Web UI. Default bind in the README is http://127.0.0.1:3080. Prefer source?

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Don’t pass --host 0.0.0.0 expecting LAN exposure. The CLI reference rejects that bind today and exits with a usage error. Localhost only unless you put a reverse proxy or tunnel in front.

Pro tip: Run npx from the repo you want the agent to touch. The process treats the invoking directory as the default filesystem location – but you still must pick that path as a workspace in the UI before the composer unlocks.

First session: Models page, then workspace (order matters)

Open the UI and do these in order. Skipping step 2 is the #1 “why can’t I type?” failure.

1. Settings → Models. On the DeepSeek card, paste an API key from the DeepSeek platform and save. Docs say the route works immediately – no server restart. Keys are write-only in the UI and land in $DSH_HOME/.credentials.yaml (home defaults to $DSH_HOME or ~/.dsh).
2. Choose workspace. Add the project directory and select it. Until you do, the session composer stays unavailable – even if you launched dsh from that folder.
3. Start a session and send a concrete task. The guide’s own starter prompt works: Summarize this repository and identify its main packages.

The agent can read and edit workspace files, run commands, delegate work, and keep a plan. The Web UI asks before operations that need approval under the active permission policy.

Want Anthropic, OpenAI, or a company gateway? Use Add provider or Add a custom provider in the same Models UI. The providers guide covers catalog endpoints, custom base URLs, and errors like MISSING_CREDENTIAL / UNKNOWN_MODEL.

Pick a runtime mode on purpose

Same plugins, different presets. Choose based on the job, not the marketing names.

That Minimal detail matters. Public agent scores shipped with V4-Pro were measured in use minimal mode. If you run Standard with a fat toolset, you’re not reproducing those numbers – you’re running a different system.

Real walkthrough: map a repo, then fix one failing path

Here’s a tight loop that shows the product instead of another feature list.

1. Start dsh web inside a small TypeScript or Python project.
2. Add your DeepSeek key; select the workspace.
3. Prompt: “List the top-level packages/modules and the command that runs unit tests. Don’t change files yet.”
4. Approve any read/shell prompts you agree with.
5. Follow-up: “Add a failing unit test for bug X, run the suite, then implement the smallest fix that turns it green. Stop after green.”
6. Open Trajectory. Check which tool results actually entered context – not what you assume entered.

That last step is the part worth checking every run. The session log is append-only: system prompts, reasoning, tool calls and results, subagent scheduling, context injections. Resume, fork, search, and replay ride the same event stream. On HN, people immediately called out inspectable traces as the feature closed U.S. stacks often hide.

Data-wise, default posture is local-first. Inputs, outputs, tool records, and stored API keys stay on your machine unless you opt into reporting or you call external model/web/MCP services that upload under their own policies – that’s the line in DeepSeek’s data-processing statement.

Gotchas that burn first-hour users

• Preview means churn. GitHub’s banner is not soft: compatibility-breaking changes will land. Prototype and write plugins; don’t freeze a production SLA on v0.1 APIs.
• Vision is not automatic on custom models. Hand-entered models are treated as text-only until you declare input: [text, image] in settings.yaml. DeepSeek’s own chat-completions route is documented as text-only here, so image attach fails until modalities match what the endpoint actually accepts.
• Provider setup isn’t always “paste a key.” Catalog cards and custom OpenAI-compatible endpoints follow the providers guide; wrong credential shape surfaces as MISSING_CREDENTIAL or UNKNOWN_MODEL instead of a friendly wizard.
• Composer stays locked without a selected workspace. Starting dsh inside the repo is not enough – the UI still needs an explicit workspace selection.

Is a fully pluginized coding agent overkill for “rename this function”? Sometimes yes. For anything that spans files, tests, and recovery loops, the use layer is the product.

FAQ

Is DeepSeek use free?

The software is MIT-licensed and free to run. You still pay your model provider. Check DeepSeek’s live pricing page before you budget a long agent farm – launch coverage around the mid-August 2026 window already flagged higher API prices with the V4-Pro push.

Do I need DeepSeek models only?

No. Configure DeepSeek for the default path, or add Anthropic, OpenAI, and custom OpenAI-compatible endpoints from Settings → Models. Example: keep DeepSeek for bulk coding loops and point a second provider at an internal gateway. Quality still depends on the model you mount for tool use; the use won’t rescue a weak tool-caller.

Is this ready to replace Claude Code tomorrow?

Not as a drop-in product replacement. You get a serious local coding-agent loop (files, shell, search, plans, subagents, approvals) and you can swap backends and sandboxes freely. You don’t get years of product glue: hosted background agents, polished multi-IDE distribution, the whole managed surface. For builders who want an open runtime to extend – especially around DeepSeek V4 – it’s the most direct official starting point available right now. Assume APIs will move.

Next action: open a terminal in a throwaway repo, run npx @deepseek-ai/dsh web, paste a key under Settings → Models, select the workspace, and force one green test cycle before you customize a single plugin.