Independent, source-backed, agent-first

Operate the harness, not just the model.

Source-backed guides and local tools for installing, operating, and debugging the official DeepSeek AI agent runtime.

DeepSeek Harness Handbook map showing agent runtime, tools, policy, sessions, MCP, and production paths
173canonical English guides
Version-pinnedrc and alpha claims identify their exact source revision
Primary sourceslinked from version-sensitive claims
Independentmaintained by SandBase, not DeepSeek AI

Latest field signals · 30 August 2026

Three failures, three different owners.

Each route starts from a current official report, pins the implementation evidence, and ends with a reversible recovery test.

Streaming · tools · persistenceEmpty continuation fields can erase a valid callBoth rc.2 and tagged alpha.1 need a regression that retains the first identity and rejects a never-identified tool call Sessions · storage · startupOne corrupt Session can hide the whole workspaceSeparate the outer plugin-loader error from the inner Zstandard frame failure, then quarantine one artifact macOS · sandbox · runner startupHost lookup is not provider startupClassify spawn sandbox-exec ENOENT separately from a denied file effect and keep unavailable backends fail closed Subagent · version · route fidelityThe same 400 has two version branchesrc.2 drops effort; alpha.1 carries it, so prove the active package graph before calling the symptom a regression Identity · provenance · installation safetySearch ranking is not project provenanceVerify the official repository, npm integrity, release commit, installer permissions, and binary signature before executing or entering credentials Filesystem · URL · capability boundaryA URL is not a local pathReject HTTP(S) before path resolution and route remote retrieval to a web/fetch capability Firefox · Web client · bootstrapBlank is a browser boundary until proven otherwiseCompare the same server, preserve the first Console/Network failure, and isolate clean-profile behavior before touching Sessions Auth · token · extension bridgeAcquisition and entry are different contractsSeparate callback, UI, storage, scope, and outbound-header evidence without exposing credentials

Five-minute first run

Start with evidence.

Launch the official Web profile from a disposable workspace, choose a model, and begin with a bounded read-only task.

First confirm that you have the official DeepSeek AI Agent runtime, not a same-name API wrapper.

Terminal
npx @deepseek-ai/dsh web
  1. Choose the workspace.Select the exact disposable repository the agent may inspect.
  2. Configure the model.Use a limited credential with an environment spending cap.
  3. Ask for evidence.Require real file paths and stop before writes or external effects.
  4. Inspect the graph.Run dsh --profile web --dump-config before changing policy.

A runtime is a composition.

A profile resolves bundles and patches into one Cordis graph. The model is one adapter inside that graph, not the product boundary.

Model
Provider, endpoint, credential reference, and reasoning route.
Effects
Tools, approval policy, sandbox, and independent verification.
Session
Durable events that reconstruct model-visible history.
Surface
Web, headless, SDK, or a custom client over the same runtime.

Pick the path that matches the job.

Explore 173 canonical guides. Each one states the expected evidence, failure branch, and safety boundary.

Prompt assembly · provenance · schemasTrace the three prompt pipelinesSeparate stable sections, runtime-fact snapshots, and tool schemas before changing a plugin or mode GitFlow · Agent policy · auditTurn branch rules into an execution guardBlock protected refspecs before spawn, keep an external audit trail, and retain repository branch protection as the final authority Vision fallback · routing · provenanceKeep a text Agent while routing images safelyUse a bounded vision adapter, preserve derived-evidence provenance, and measure the second request honestly DSH_HOME · concurrent instances · SessionsKeep workspace membership from being prunedSeparate home-level stores, stop multi-writer metadata races, and recover Sessions that fall into Ungrouped Context · compaction · cache evidenceCompress tool context without hiding the tradeoffSeparate Fresh, History, and TailTrim paths, preserve recovery, and measure cache invalidation honestly Terminal lifecycle · jobs · message durabilityThe timer is not the processClassify foreground Bash, background jobs, persistent terminals, and stale presentation before retrying Models UI · vision · route metadataSelectable is not image-capableAuthor one narrow model modality, preserve hidden fields, and prove the resolved route with a fresh Session Questions · cancellation · replayNo answer is not a timeoutTrace the owning signal, keep reconnect separate, and design reminders independently from typed decision deadlines Tools · edit · Agent assemblyUnknown tool means no tool body ranMap the current Preset and tool mode before changing file permissions or guessing another editor name Settings · plugins · overflowClipped is not absentMake the section list the bounded scroll owner while keeping the title, close action, and content scroll independent Sessions · navigation · workspaceA sidebar label is not an execution rootSeparate mutable Collections from cwd, Workspace accounting, sandbox policy, archive, and no-Workspace execution profiles Tools · Web card · languageThe tool knows the languageMove grammar intent out of the reserved wire name while keeping highlighting separate from runtime and policy authority Subagents · inbox · authorityYour follow-ups are not the whole inboxList and cancel one direct parent's pending subsequence without moving settlement notices or losing claim-race evidence Host heap · cold restore · supervisionCompaction is not heap collectionSeparate retained growth, synchronous reconstruction, Host exit, wrapper termination, and runtime-copy drift Sessions · Web presentation · compatibilityVisible is not focused; focused is not current dataBind every pane to explicit Session identity and keep one interaction authority Web UI · Client plugin · SlotMapOwn the extension; do not patch the installDiscover the seat, package both faces, cross the browser loader, and prove removal Typert · external plugin · build proofExit zero is not an artifactProve aggregate references, real-path containment, discovery, emission, and publication separately Approval · Web/Feishu · exact settlementMany observers. One decision owner.Authenticate card authority and settle click versus timeout once without racing approval channels Images · pi-ai · provider protocolImage-capable is not format-compatiblePreserve the original attachment, negotiate provider MIME types, and derive a bounded compatible rendition read_image · Cordis · service scopeVisible schema. Missing service scope.Keep attachments as the lifetime gate, pass the declared outer context, and test execution rather than visibility Sessions · archive · retentionArchive live. Trash offline.Keep official archive online, require writer quiescence and a whole-root snapshot before physical mutation Goal rounds · subagents · admissionIdle is not quiescentHold parent inference while an owned child runs, then wake once on its paired settlement edge OpenRouter · provider policy · PresetsRouting policy needs one ownerKeep DSH strict, encode stable routing remotely, and verify the endpoint that actually served the request PDF/video · route negotiation · Agent evidencePassthrough is a derived routeKeep one local attachment, bind remote files to an exact provider route, and disclose extraction or sampling Plugin UI · image result · attachmentOne image needs two presentation contractsSend pixels to the model and render an authorized Web result card without public image URLs write · edit · nested languagesCount boundaries, not backslashesCapture the tool argument, readback, exact bytes, and parser result before changing the wrong layer /compact · caller abort · lifecycleThe provider did not cancel the summaryStop retries, capture the first aborted signal, and test the Remote-token hypothesis without erasing authentic cancellation Plugin update · pnpm store · relinkOne profile resolved two store identitiesCapture linked and selected stores, pin one owner, relink once, and repeat-prove stability OpenCode Go · mixed protocols · entitlementA model listing is not a callable routeSplit Chat Completions, Responses, and Messages before diagnosing model-specific access Web boot · Client plugin · recoveryHTTP 200 can still end at Failed to load pluginsTrace arrival, registration, materialization, apply, and package ownership before removing one failed bundle Web · Firefox · browser compatibilityDiagnose a blank Web client in FirefoxCompare browsers, preserve first Console and Network evidence, and isolate bootstrap from Session failures Sandbox · dependency cache · trustA shared cache is a persistent write capabilityNamespace toolchain bytes, sharing scope, runner grants, concurrency, and cleanup before crossing workspaces Windows · Node · offlineThe version string and runtime disagreeJoin the shell probe, DSH process image, launcher, and AbortSignal global before reinstalling Web boot · pnpm · symlinkServer booted; client graph incompleteJoin bundle roster, fallback realpaths, boot manifest rows, and client bundle responses Responses API · 503 · Retry-AfterA large request is not a retry stormJoin wire attempts to durable retries and trace cancellation across the gateway Codex · hooks · policy bridgeReuse the hooks; re-prove the policyPin the bridge pair, map five supported events, and test every semantic gap Hooks · peer dependency · profileInstall the bridge and protocol; reuse the runtimePin one release line, keep core peers Host-owned, and audit hooks as executable policy ToolRuntime · module identity · lifecycleSame error, three different timelinesSeparate static duplication, relaunch, and runtime generation drift before repairing the scheduler slot Headless · embedding · automationThree flags become one public protocolDefine Session identity, exact model routing, JSON stdout, durability, and exit truth together Air gap · source build · provenanceOffline begins with identityTransfer a verified Git bundle or supply the authenticated commit, then prove closure and artifacts Token meter · signed fold · recoveryAn estimate must not brick a SessionRepair both underflowing projections, migrate checkpoints, and refold authoritative history Agent preset · shared provider ownershipOne registry needs every live holderSeparate stale generations from copied-preset collisions, then preserve disposer ownership Web · macOS · IMECandidate window first; submit guard secondSeparate missing composition from premature Enter, then capture the real event interval Security · credential storageEncryption at rest is not isolation from the AgentChoose file permissions, an encrypted envelope, a keychain, or separate identity by threat model Session · duplicate seqThe durable cursor moved backward inside committed historyProve full event identity before staging any duplicate-range repair Web · image sendThe caret is visible, but the input flight never settledRoute image preparation, Host admission, and lost acknowledgement before retrying Subagent · route fidelity · reasoningThe model route survived; one field did notCompare parent, spawn, and fork headers before changing credentials or budgets Headless · reasoning effortThe command owns the task; the model route owns effortChoose shared defaults, provider policy, or an isolated overlay—and verify request/header Bailian · catalog routeKeep the provider identity and its compatibility factsPreserve reasoning metadata, avoid developer-role 400s, and treat models as replacement Custom provider · protocol collisionEndpoint is not protocolProve provider id, explicit api, catalog stream ownership, and the final request path MCP · expired sessionThe transport can be open while the session is deadInvalidate one stale generation, rediscover tools, and circuit-break repeated application-level failures Web Search · custom gatewayChat and search are different routesMatch the Anthropic endpoint, credential reference, native server tool, and structured result—or disable the mismatch npx · npm exec · install boundaryFind the hang before Harness startsSeparate confirmation, registry, cache, lifecycle scripts, CLI entry, and Web listen without destructive cleanup Model stream · repetition guardReject degenerate repeated outputBound the detector, preserve terminal stream truth, measure false positives, and make Agent retry an explicit finite policy Tool cancellation · process ownershipAccepted Stop is not settled idleTrace signal delivery, process-tree quiescence, preserved inbox work, and restart recovery before retrying Plugin tools · Windows · crash isolationA child failure is one tool outcomeSeparate process identities, contain pipes and rejection, and prove the official Host survives Windows · Web Host · post-message hangThe port listens; the Host does not answerJoin PID, probes, and three private full dumps before blaming Node, zstd, a proxy, or a native module ACP · reverse requestTerminate every permission decisionTrace an unanswered request, apply one bounded policy or UI decision, and fail closed without hanging the turn ACP · Web permission UIRender a minimal permission request honestlySeparate correlation identity from missing tool presentation, then fail closed or join an authoritative host registry Provider overload · pi-aiRecover a server_error with no retryProve provider evidence, classification, route policy, and durable retry event pairs Profile boot · package closureFind a corrupt package.jsonScan read-only, identify the install owner, preserve evidence, and replace the exact closure Windows desktop · tool processStop console windows flashingSeparate local Node spawn from restricted-token ACL sandbox creation without disabling policy Profile boot · user overlayUnbrick an invalid cordis.patch.ymlPreserve both user layers, prove the default composition, remove the unresolved insert, and restore transactionally Session persistence · packed rowsRead logs without losing assistant outputDecode concatenated Zstandard frames, three packed-row types, and one contiguous logical event stream Product selection · control planeCompare DeepSeek Harness, Claude Code, and CodexChoose by runtime ownership, extensions, policy, durable state, and the product you are actually shipping Plugin closure · npmResolve a missing schema-form packageTrace the importing plugin, selected DSH distribution, package tags, and duplicate-runtime risk before adding anything Reasoning model · Session titleProve the auxiliary output budgetSeparate the deterministic fallback from LLM refinement, inspect the exact title request, and recover without changing the main Agent turn Interactive toolGenerate an install evidence planChoose OS, install path, and first failure to get exact commands, a success signal, and the matched source-backed guide Community ecosystem · 82 resourcesChoose a DSH resource by capabilityStart with four bounded Agent paths, then browse the pinned Awesome snapshot for source-linked skills, memory, routing, research, UI, file, and security resources with install and rollback boundaries SandBase integrationConnect a real MCP runtimeRun SandBase Harness behind a stdio bridge with explicit Session, sandbox, credential, and rollback boundaries npm install · rc.8Route ETARGET by registry identityCompare configured and official metadata, prove with an isolated cache, and preserve prerelease-family integrity Code Mode · tools:sdk · literal textGenerated SDK text is not a prompt templateRoute unknown and malformed double-brace groups through an explicit raw section while authored templates stay strict Node 24 source buildCatch a successful no-op buildRequire the artifact record, route import.meta.main entrypoint failure, and recover before missing outputs collapse into loader fibers failed Source build · Rolldown · lib/typesGenerated output belongs to a revisionProve importer/owner drift, clean repository outputs safely, and rebuild against the frozen lockfile Stuck Turn · cancel · retryStop first. Prove closure.Reconcile side effects, then choose a revised follow-up, branch, or clean Session TUI · slash commands · adapter ABIOne shifted argument breaks every commandRestore the image-array and AbortSignal positions, then verify both registry dispatch paths Web boot · client modules · /pluginsThe loader exists. Its registration does not.Capture one generation and route HTML injection, bundle bytes, script order, and proxy cache ACP · stdio · multi-tenant gatewayHTTP does not create a tenant boundaryBind principal, child generation, connection, Session, replay, permission, and teardown ownership ACP automation telemetryFinal text is not a control planeMeasure committed-message output, missing tool lifecycle and usage facts, and the contracts required for observable automation Plugin tool schemaRoute additionalProperties and union errorsSeparate implicit roots, explicit DSL objects, raw JSON Schema defaults, and exact-one oneOf behavior Plugin transactionRecover a partial plugin installSeparate materialization, build output, bundle reconciliation, and bootability after pnpm exits nonzero Session projectionRecover an update-before-start failurePreserve the log, isolate replacement-copy ordering, and require one repair contract across live, window, and replay paths Linux · macOS · Windows source buildStop Node from parsing the pnpm entrypointClassify JavaScript, ELF, shell, and Windows launchers before restoring the rc.8 gate chain Session storageFix hard-link publication failuresMove the Session root safely and preserve atomic no-clobber durability on HarmonyOS, NAS, network, and restricted filesystems Cost boundaryPrevent unexpected DeepSeek API chargesSeparate catalog visibility, route registration, route selection, credentials, and observed egress before claiming zero spend AGENTS.md · visibility · enforcementGuidance is not a policy gateProve the rule loaded, resolve authority, then enforce destructive and security invariants outside model prose MCP toolsCompose one server into an Agent presetStart a fresh Session, prove scoped discovery, and route stdio, HTTP, registration, and reconnect failures Provider egressRoute API fetch failuresSeparate Node proxy discovery, enterprise CA trust, browser ingress, and provider HTTP status before changing the model Windows pickerRoute crashes and Unicode truncationSeparate Node/Koffi aborts, U+XX00 low-byte corruption, native installation, and stale-process failures before switching to browse mode CLI mapChoose Web, headless, or a profileUse the shipped launcher correctly and keep community terminal UI behind its own audit boundary Memory architectureChoose what crosses SessionsSeparate Sessions, Skills, application records, and long-term memory before migrating Codex or Claude Code state Session ownershipKeep writable roots single-writerIsolate concurrent processes or serialize shared-history handoffs before stale cursors interleave Workspace recoveryExplain a misleading spawn ENOENTVerify the executable, test the Session cwd, and recover without writing into an empty directory UpgradePreserve the way backTest an exact target in an isolated home, pass compatibility gates, and prove full-state rollback Plugin market · verdict provenance · Host mutationTested is not security-reviewedBind the verdict to exact bytes and authorize each install, update, patch, and rollback separately InstallationChoose the right execution topologyVerify the official package, pin the artifact, and separate executable, state, and workspace Skills tutorialCreate reusable Agent instructionsAuthor one SKILL.md, route it by description, invoke it directly, and debug discovery Plugin tutorialBuild your first DSH pluginLoad one module, register a typed Agent tool, package a bundle, and prove installation Project identityVerify the official runtimeMatch the repository owner, npm scope, release commit, and executable before installing macOS workspaceRemove one leaked path separatorProve the terminal colon, preserve realpath identity, and recover without renaming the volume Global installTrace a missing native bridgeSeparate an isolated pnpm platform-package failure from the misleading plugin-not-found fallback Plugin durability · registration · alpha.1A type name is not a compatibility contractSeparate optional observations, required state, foreign imports, ownership, schemas, and cold readers Source startupRoute the HMR internals errorSeparate the visible Node flag from pinned-pnpm and native-helper discovery failures Security boundaryDecide where Code Mode may runSeparate worker containment from OS isolation, then choose native tools or an authoritative outer boundary Windows recoveryRelease a blocked config replacementSeparate an HMR handle conflict from ACL denial, then edit through a reversible lifecycle Performance triageExplain slow first-token latencySplit Host outbound, provider, and Host inbound time before changing the model route Session recoveryEscape recurring invalid JSONExport evidence and recover from malformed tool-call history without editing a live log Stream · persistence · recoveryContain an empty tool identityTrace one empty call through UNKNOWN_TOOL, replay 400s, and a rejected Session resume Events, not intentionsRoute narration without tool callsSeparate one bad stream from repeated turns, find every wake source, and stop actionless automation Persistence safetyProtect live session logsStop the writer, preserve evidence, and separate crash tails from committed corruption Host compatibilityFix a missing /bin/bashPatch the persistent PTY owner on NixOS and non-FHS hosts Repair · plugin compatibility · profileRepair one layer. Never erase the home.Route runtime-export drift, choose one compatible closure, and prove a reversible repair through cold boot Capacity guideBound subagent scaleTwo limits, one heap boundary, and restartable batches Provider guideConnect local OllamaExact form values, host preflight, and container localhost alpha.1 · Models UI · provider recoveryRoute a silent Add provider actionSeparate stale client/Host wiring, validation, settings, route registration, and inference Session identity · plugin notice · ZstandardReject unidentified messages before persistenceTrace producer construction, inbox correlation, cold-load validation, and repair-induced frame damage Operator noteCapture the version that executedSeparate npm tags, installed artifacts, and source revisions CurrentCheck rc.7 baseline + alpha.1 contextKnown boundaries, migration seams, evidence, and safer next actions InteractiveRoute a failure in 30 secondsPick the first broken boundary and collect the right evidence Remote Settings · identity · capabilityHTTPS is not a Settings grantAuthenticate the gateway and browser principal separately, then authorize narrow Host-enforced operations Remote Web · Origin 403Keep the shell behind exact authority and identitySeparate UUID failures from extension-rewritten Host and Origin authorities before changing the trust fence Context overflow · compactionRecovery must fit and convergeClassify provider wording, price both request envelopes, and stop identical failed ranges WebView · renderer · CPU 100%The stack proves a loop—not its ownerTrace observer registration, shell provenance, injected scripts, and one immutable Session fixture RTL · Arabic · Hebrew · mixed scriptsDirection is semantics—not alignmentDesign authored direction, inference, block overrides, inline isolation, code safety, and composer geometry Generation ceilingDiagnose a truncated answerSeparate request maxTokens, provider capability, and remaining context headroom before retrying Compaction checkpointFix a summary truncated at 8,192 tokensSeparate local-server context shift from durable Session replacement, then tune the summary cap or route Model routingSeparate a session switch from the future defaultMap live selection, Settings persistence, durable request evidence, and future Agent inheritance Plugin HTMLStop replacement strings from rewriting scriptsDistinguish the Harness tap pipeline from JavaScript replacement-token semantics Provider rolesFix a gateway that rejects developerSeparate reasoning metadata, wire dialect, effort support, and system-message role compatibility macOS BashStop CJK commands from stalling for 300 secondsSeparate a C-locale readline trap from PTY transport corruption, then test the narrow preset workaround Session recovery · read contractBlank is not end of historySeparate framing, sequence, identity, projection, gaps, and Remote failure before changing an artifact Plugin installFix the workspace-root rejectionApply explicit profile-root intent, then prove dependency, materialization, bundle, and composition state Plugin artifactRecover a Git plugin missing distSeparate blocked, bypassed, and broken builds; restore the profile before proving the exact installable artifact Plugin dependenciesRoute missing peer warnings safelyProve Host fallback ownership, semver compatibility, third-party gaps, and build policy before changing the profile Language controlSeparate answer from reasoning languageTest user intent, persona, provider output, gateway injection, and UI locale as distinct owners Prompt durabilityRecover text lost before the user eventSeparate optimistic clear, Host admission, inbox claim, Session durability, and provider processing Tool protocol · Session integrity · recoveryBalance the transcript; do not invent the pastClose missing results truthfully, quarantine orphans, and keep adapter containment observable Agent task stateReconcile a todo stuck in progressSeparate final prose, durable todo snapshots, turn endings, and the Web projection before adding one bounded reminder Code Mode SkillsBridge UI-visible instructions into model contextTrace one nested Skill across the worker value, durable dispatch, outer result, and next request Windows presetRoute Minimal Bash before changing the commandTrace the exact win32 inspector failure across preset, persistent PTY, subprocess, and platform support Windows ACLExplain a frozen first workspace-write callSeparate eager tree propagation from provider latency, denials, and preset failures before changing trust Synology NASDeploy the source workspace without dependency driftGate Node, pnpm links, native ABI, cwd-stable launch, service identity, and remote access separately Human interactionRecover a missing question or approval cardSeparate silent dead sockets from replay-resync clearing without manufacturing consent Provider transportDiagnose an invalid HTTP/2 sessionSeparate provider, proxy, transport, and retry boundaries Subagent · human loopRelay one clarification through the parentKeep the root Session in control, commit the answer, and resume one authorized continuable child ACP + MCPChoose the Session ownership boundaryCompare tenant Hosts, named allowlists, an authenticated gateway, and direct HTTP contribution SubagentsRoute an unknown Job identitySeparate run IDs, one-shot Job IDs, and continuable child IDs before recovering missing work Windows · 3221226505 · Fail FastOne exit code is not a root causeResolve the process, native module, WER subcode, and last durable boundary before reinstalling Incident notePrevent subagent route driftWhy a child agent may use the wrong provider and credential Web UIExplore interactivelyWorkspace selection and a first safe task HeadlessAutomate one bounded jobExit codes, artifacts, diffs, and CI evidence Python SDKEmbed the runtimeJSON-RPC lifecycle and platform boundaries MCPConnect external capabilitiesProcess, transport, handshake, registration, policy TroubleshootingDiagnose by symptomSeparate provider, loop, policy, sandbox, and tool failures

A prompt is an instruction. The boundary lives in policy, isolation, and evidence.

Pin the runtime. Review the resolved graph. Separate credentials by environment. Test denial, timeout, partial completion, and cleanup.

Open the operator cheat sheet

Build on facts that can be replayed.

The handbook is independent, open source, and verified against primary DeepSeek Harness sources.

Read and star on GitHub