Overview

DeepSeek Harness keeps Agent and Session relationships common while profiles choose the surrounding lifecycle. Web supports long-lived browser interaction, headless owns one task and exits, SDK serves open-ended JSON-RPC events, and ACP provides a standard persistent automation contract with documented omissions. The chapter also compares full and minimal compositions, browser extension seams, fresh, forked, and out-of-process children, and dynamic packages. The choice is governed by interaction, settlement, inherited history, persistence, and trust: scopes share a process, out-of-process children have stronger process separation but remain environment-dependent, and dynamic packages are runtime extension rather than sandboxing.

Learning outcomes

Profiles change lifecycle and transport around a shared Agent and Session core rather than creating four unrelated applications.
Web, headless, SDK, and ACP differ in interaction and settlement contracts, so no surface is a universal winner.
Child processes and dynamic packages add boundaries or extension points, but neither is automatically a complete security isolation.

Keywords

DeepSeek HarnessProfilesWebHeadlessSDKACP

One Core, Four Surfaces: Profiles, SDKs, and Extensions

DeepSeek Harness uses profiles to make one Agent and Session architecture serve different kinds of users. This chapter compares the Web, headless, SDK, and ACP surfaces by interaction model, lifecycle, persistence, and trust boundary, then applies the same criteria to browser extensions and child agents. The practical question is not which surface has the longest feature list; it is which composition matches the work that must be owned and the boundary that must be enforced.

A profile is an ordered composition of bundles and patches. It selects plugins over an empty root, and later layers can replace a complete row by id. That makes the profile a runtime decision: it determines whether the process owns a browser server, a one-shot result, a JSON-RPC connection, or a standard automation session. The Agent loop and Session log can remain common while the surrounding lifecycle changes.

Profiles change the surrounding lifecycle

The shared base composition supplies model access, tools, session persistence, credentials, permissions, and other core capabilities. The Web overlay adds a host server, browser connection, client-module graph, UI slots, and session controllers. The headless overlay adds a runner that creates one fresh Agent, waits for its owned interval to settle, prints the final answer, and exits. The SDK overlay adds a JSON-RPC server whose stdout is reserved for protocol frames. The ACP overlay adds a standard automation server with persistent sessions and semantic updates.

These are not four independent applications that happen to call a model. They are four ways of owning the same Agent and Session relationships. The Web surface keeps a process alive for interactive sessions. Headless owns one task and maps its final turn outcome to a process exit. SDK accepts prompts and publishes open-ended session and status notifications; a message id acknowledges inbox admission rather than identifying a future assistant answer. ACP owns a more structured prompt interval and can close a session independently while preserving it for later resume.

The profile system also preserves a deliberate exception. sdk-minimal is a complete standalone tree that provides a small coding-agent runtime rather than layering over the shared base. It keeps a persistent shell and JSONL sessions but omits many base services, including the full tool roster, settings, managed credentials, Web tools, telemetry, compaction, and subagents. The choice is explicit: a smaller composition is easier to carry for a narrow SDK use case, but it gives up shared product features and uses a more permissive shell policy.

Patch precedence makes customization powerful and easy to misunderstand. Bundles apply in their listed order, followed by the profile patch, the Harness-home patch, and an invocation overlay. A matching patch replaces the whole configuration for a row rather than deep-merging it. An operator who changes a model or permission row must restate the settings they intend to keep. This is a composition contract, not a promise of compatibility across developer-preview releases.

Reload policy follows lifecycle ownership. The Web profile can apply user patch changes live because it is designed around an ongoing interactive process. Headless, SDK, ACP, and the minimal SDK profile apply patches at startup. Replacing a model server, protocol bridge, or Agent dependency while a one-shot or stdio application owns active work would make the lifetime ambiguous, so these surfaces prefer a stable tree until restart.

Published by DeepMox

FAQ

Which DeepSeek Harness surface should a one-shot script use?

Headless mode is designed for one task: it prints the final answer, exits after its owned work settles, and opens no server.

What does the DeepSeek Harness SDK prompt response mean?

An SDK prompt response is an admission receipt, not a per-prompt assistant result; clients observe open-ended session and status events for later progress.

When should a DeepSeek Harness child agent run out of process?

Use an out-of-process DSH SDK child when it needs its own profile, persistence root, model route, and tools; it creates a stronger process boundary than an in-process scope but is not automatically isolated.

Previous10 minDeepSeek Harness: Replay and Compaction

Next13 minDeepSeek Harness: Capabilities and Limits

DeepSeek Harness: Profiles and Surfaces

One Core, Four Surfaces: Profiles, SDKs, and Extensions

Profiles change the surrounding lifecycle

FAQ