跪拜 Guibai
← All articles
DeepSeek · Agent

DeepSeek Harness Is a Runtime You Assemble, Not a Chatbot You Launch

By 纯爱掌门人 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Agent frameworks that treat the runtime as a fixed product force developers to work around built-in assumptions. Harness makes the runtime itself the thing you compose, which means security policies, tool access, and model behavior can be swapped per task without forking the project.

Summary

The tool separates credentials from configuration, enforces a workspace selection step before any file access, and logs every turn, tool call, and approval as replayable session events. A permission pipeline sits between model output and filesystem access, making policy the real security boundary rather than prompt instructions. Custom models require explicit capability declarations, and misconfigured multimodal settings can corrupt session logs in ways that a config change alone won't fix. Web and headless modes share the same core, differentiated only by which Bundles load at startup. Patches let developers experiment without touching source code, and custom Profiles turn a set of plugins into a persistent, purpose-built agent for code review, writing, or sandboxed execution.

Takeaways
— Harness disables the input box until a workspace is explicitly selected, preventing accidental filesystem access from new sessions.
— Credentials live in a separate .credentials.yaml file, and the Web UI only returns a desensitized description after saving, never the plaintext key.
— Custom Provider IDs are written into session logs and credential references; renaming one in-place breaks existing sessions, so the correct path is to add a new Provider and migrate.
— Manually added models default to text-only; multimodal models need an explicit input: [text, image] declaration, and a bad declaration can corrupt session logs in ways that config edits alone won't fix.
— Web and Headless modes share the same underlying engine and differ only by which Bundles load—Web adds a server and frontend, Headless adds a one-shot task runner.
— Patches loaded via --patch apply only for that launch, making them a safer way to experiment than modifying built-in Bundles.
— Custom Profiles persist a set of plugins as a reusable agent variant, stored under $DSH_HOME/profiles/<name>/ with a package.json and cordis.patch.yml.
— A session is an event log of Turns, Steps, model outputs, and Tool calls, not a chat history; this means model changes mainly affect new sessions, and old sessions retain their own model records.
— Tool calls pass through a pre-execute, permission, execute, and post-execute pipeline before touching the filesystem, making Provider-level policy the actual security boundary.
— Running --dump-config is the only reliable way to see the final plugin tree when Profiles, Home configs, and multiple Patches overlap.
Conclusions

The workspace selection gate is a deliberate design choice that makes the agent's filesystem scope explicit, rejecting the common pattern of inheriting the launch directory as an implicit working context.

Separating credentials from configuration into a dedicated YAML file with desensitized reads is a practical defense against accidental key leakage in config diffs and logs—more agent runtimes should adopt this.

The session-as-event-log architecture means Harness can replay, fork, and resume sessions deterministically, but it also creates a footgun: stale multimodal declarations persist in the log and can't be fixed by editing current config alone.

Patch-based experimentation and Profile-based persistence together form a plugin development workflow that doesn't require forking or rebuilding the core project, lowering the barrier to custom agent tooling.

The permission pipeline that intercepts tool calls before execution is architecturally more honest than prompt-based guardrails; it acknowledges that model output is untrusted input to a policy engine.

Concepts & terms
Profile
A named configuration that bundles a set of plugins, Bundles, and Patches into a specific agent runtime variant. Profiles let the same core engine run as a Web UI, a headless task runner, a code reviewer, or a sandboxed executor.
Patch
A YAML file that overlays plugin insertions or modifications onto a Profile at launch time without altering the built-in Bundles. Patches apply only for that single run, making them safe for experimentation.
Session Event Log
Harness records every Turn, Step, model output, and Tool call as structured events in a session log, rather than storing a simple chat message list. This log drives the UI, model context, and replay/fork capabilities.
Tool Call Permission Pipeline
A chain of hooks (pre-execute, permission check, execute, post-execute) that sits between a model's tool call output and actual filesystem or process access. It enforces policy at the Provider level rather than relying on prompt instructions.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗