2026 DeepSeek Harness Run Modes: Web, Headless, Or ACP

As of August 18, 2026, the DeepSeek Harness run modes have a clear decision rule: use Web for daily interactive work and human approval, Headless for repeatable scripts or CI jobs, and ACP only when another editor or agent system must create sessions and consume structured results. Teams can keep several entry points, but model routing, workspace permissions, plugin versions, and acceptance checks should stay aligned.

This guide is for three groups:

• Independent developers who want the least-maintenance daily workflow.
• Automation engineers who need predictable commands, logs, exit states, and retries.
• Platform or tool developers who must evaluate ACP integration without creating a second configuration system.

Last updated August 18, 2026. Current commands and behavior were checked against the official repository README, Web UI guide, development guide, and architecture documentation. DeepSeek Harness remains in developer preview, so commands and compatibility may change.

Start With The Responsibility, Not The Interface

The main difference between Web, Headless, and ACP is not model intelligence. The same underlying agent architecture can be composed through different profiles. The difference is who controls the session, who sees intermediate actions, and who must recover when something fails.

The official documentation describes web and headless as profile templates. The Web profile adds the browser application, while the Headless profile adds a one-shot runner without a server. The architecture also treats the session log, tools, approval policy, model adapter, and agent loop as replaceable plugins. See the official DeepSeek Harness architecture documentation.

Use this first-pass rule:

• Choose Web when the task is ambiguous, changes files, runs tools, or needs a person to inspect the plan.
• Choose Headless when the input is bounded, the output can be validated, and a process can determine success without reading a screen.
• Evaluate ACP when an external client must start sessions, send prompts, receive events, cancel work, or map permissions into its own workflow.

This distinction prevents a common mistake: selecting a more programmable entry point before the task itself is stable.

Choose Web For Visible Daily Work

The Web UI is the best starting point for an independent developer who still needs to watch what the agent is doing. The official Web guide requires a workspace before the session composer becomes available, and it describes approval prompts for operations governed by the active permission policy. The Web command is currently npx @deepseek-ai/dsh web, with the server using http://127.0.0.1:3080 by default. See the official DeepSeek Harness repository and Web UI guide.

Web is useful when the developer needs to:

• Inspect the plan before execution.
• Review tool calls and file changes.
• Approve sensitive operations one at a time.
• Continue a task after a partial result.
• Compare the agent’s proposed action with the actual workspace state.
• Preserve a visible session record for later review.

The advantage is observability and intervention. It does not mean the model is automatically more capable in Web mode.

What is the practical difference between DeepSeek Harness Web and Headless?

Web keeps a server and browser interface around the agent session. Headless runs a one-shot task without that server. Web makes human review easier; Headless makes process-level automation easier. Neither should be treated as a universal performance upgrade.

For daily coding, Web is usually the safer choice when the task can expand beyond its initial description. A request such as “update the authentication flow” may require discovery, edits, tests, and a decision about backward compatibility. That sequence benefits from visible checkpoints.

A developer should not build a custom automation wrapper for occasional work merely because Headless looks more technical. The wrapper adds responsibility for environment preparation, output capture, timeout handling, and failure recovery. If the task happens only a few times per month, those costs can exceed the time saved.

Use Headless For Repeatable Tasks

Headless is the better fit when a task has a narrow contract. The official development guide shows a one-shot invocation using the headless profile:

pnpm dsh --profile headless "summarize this workspace"

The same guide states that the Headless demo reads DEEPSEEK_API_KEY from the environment or a repository-level .env file. See the official DeepSeek Harness development guide.

A Headless task should have four properties:

1. The input boundary is explicit.
2. The expected artifact is defined.
3. Validation can run without human interpretation.
4. Failure can be represented by a non-success process result or a machine-readable error.

Examples include repository summaries, documentation generation, static analysis assistance, test-failure triage, changelog drafts, or controlled code transformations followed by a test command.

Can DeepSeek Harness be called from a script?

Yes. The official development examples show that the Headless profile can be launched from a command. A script can pass the task as an argument, set credentials through environment variables, capture standard output and error output, and apply its own validation after the process ends. The important point is that the script owns the contract around the agent; DeepSeek Harness does not automatically know whether a generated file is acceptable.

A reliable wrapper should separate four concerns:

• Parameters: pass workspace paths, task text, profile names, and feature switches explicitly rather than relying on the current shell state.
• Secrets: keep API keys in environment variables or a secret manager; never place them in task arguments or committed files.
• Logs: save the command, profile, commit identifier, start time, output, error output, and final validation result.
• Recovery: define whether the next attempt reuses the workspace, resets it, or starts from a clean checkout.

Headless does not remove approval responsibility. If the task can delete files, alter deployment configuration, change access control, or write to production-connected resources, the safe pattern is to place a test gate or external approval step after the agent and before the write is accepted.

For CI, a useful sequence is:

prepare workspace
→ launch Headless
→ capture session and process output
→ validate generated artifacts
→ run tests or policy checks
→ publish result
→ preserve evidence

The hidden cost is not starting the command. It is maintaining the boundary around it.

Treat ACP As An Integration Contract

ACP is appropriate when DeepSeek Harness becomes a service inside another tool rather than the primary interface for a person. The official development guide describes an ACP automation server that exposes fresh agent sessions over JSON-RPC stdio and shows the acp profile as an alternative runtime for the self-referential demo. See the official ACP development reference.

When does an integration actually need ACP?

ACP becomes reasonable when an upper-level client must perform several actions programmatically:

• Create a new session.
• Send one or more prompts.
• Receive structured progress or result events.
• Cancel an active session.
• Translate external permissions into Harness permissions.
• Keep the user experience inside an editor, orchestration tool, or agent platform.

If the requirement is only “run one task from a shell,” Headless is usually simpler. If the requirement is “let another client manage many sessions and display their state,” ACP deserves evaluation.

ACP introduces several failure points that Web and Headless do not expose in the same way:

• Client compatibility: the calling application may implement only part of the protocol.
• Lifecycle management: sessions need creation, cancellation, timeout, cleanup, and possibly resume behavior.
• Error propagation: a transport-level success does not prove that the agent task succeeded.
• Permission mapping: the upper-level client and DeepSeek Harness may use different names or scopes for approval.
• Event ordering: structured events must be correlated with the correct session and task.
• Upgrade testing: a developer-preview change can affect both sides of the protocol.

The correct approach is to create a small compatibility test before committing to ACP. Start a session, send a harmless prompt, receive the expected response, cancel a second session, and verify that an intentional failure reaches the caller in a recognizable form.

Do not replace a stable Web or command-line workflow merely because ACP offers a more flexible interface. Flexibility is valuable only when another system will actually use it.

Keep Team Governance Consistent

A small team does not need one mandatory entry point. A developer can use Web for exploratory work, an automation engineer can use Headless in CI, and a platform engineer can expose ACP to a higher-level tool.

What must be unified is the execution policy around those modes.

Centralize these settings:

• Model provider and model route.
• Default profile naming.
• Workspace and filesystem boundaries.
• Shell and subprocess permissions.
• Plugin versions and lockfiles.
• API credential handling.
• Log retention and redaction rules.
• Artifact validation requirements.
• Approval requirements for destructive operations.
• Rollback and recovery procedures.

Allow individuals to keep these preferences:

• Browser versus terminal interaction.
• Prompt drafting style.
• Session naming conventions.
• Local display preferences.
• Whether exploratory work begins in Web or a command-line session.

The distinction matters because different entry points can otherwise produce different evidence. One user may approve a file write in Web, while a Headless job performs a similar write without recording the same decision. The task may appear identical to the model, but the audit trail is not equivalent.

The architecture documentation states that model-visible inputs must be reconstructable from the session log and that durable session events support replay, transcripts, telemetry, and persistence. Teams should use that principle when defining their own evidence standard.

A practical team policy is:

• Same model configuration across modes.
• Same workspace classification across modes.
• Same approval level for the same class of action.
• Same artifact checks after execution.
• Same retention period for logs and outputs.

Different interfaces are acceptable. Different safety standards are not.

Check The Maintenance Boundary

The developer preview status is not a minor footnote. The official README warns that compatibility-breaking changes may occur while the project iterates.

The current development guide lists Node.js support beginning at version 22.19 and also covering version 24, while the repository pins pnpm@11.7.0 through its package configuration. These are useful setup facts, but they are not permanent guarantees. Recheck them before building a long-lived runner. For the runtime requirements, consult the official Node.js release documentation. For package-manager behavior and version management, use the official pnpm documentation.

Maintenance responsibility differs by mode:

• Web: maintain the server process, browser access, workspace selection, authentication settings, and remote access controls.
• Headless: maintain process invocation, environment variables, log capture, timeouts, retry rules, workspace cleanup, and validation.
• ACP: maintain all of the above where applicable, plus protocol compatibility, session routing, event correlation, cancellation, and permission translation.

Remote access creates another boundary. A Web service that is convenient for one developer can become risky if exposed beyond the intended network without authentication, workspace isolation, and a clear shutdown path. A persistent ACP process also needs health checks and resource limits; otherwise disconnected clients can leave sessions or child processes behind.

For a remote Mac workflow, the operating environment matters as much as the profile. A controlled machine with stable access, known permissions, and repeatable setup is easier to maintain than a developer laptop that changes frequently. RUVCLOUD can be considered when the goal is to test a remote Mac environment before committing to a long-term machine purchase. The RUVCLOUD service entry point can be used as the next step after the runtime choice is clear.

Run One Baseline Task Before Committing

The best mode decision is based on the same low-risk task, not on a feature checklist. The task should read a small workspace, produce a bounded artifact, and include a deliberate validation step.

Use this five-stage comparison:

1. Prepare one workspace. Use the same files, branch state, model route, plugin set, and permission policy.
2. Run the Web version. Record startup steps, workspace selection, approval prompts, visible tool activity, and final artifact.
3. Run the Headless version. Record command arguments, environment variables, stdout, stderr, exit behavior, and validation results.
4. Run the ACP version. Record session creation, prompt delivery, event reception, cancellation behavior, and error propagation.
5. Write the decision as an operating rule. Name the primary entry, fallback entry, and prohibited scenarios.

A suitable baseline might ask the agent to summarize a repository and write the result to a new file. It should not modify production settings, delete files, or access confidential data.

Decision matrix

Ownership comparison

Rollout plan

Use this checklist before making the mode permanent:

• [ ] The task has a defined input boundary.
• [ ] The expected artifact has an automated or reviewable acceptance rule.
• [ ] The model configuration is identical across compared modes.
• [ ] Workspace permissions are documented.
• [ ] API credentials are injected without appearing in logs.
• [ ] Web approval behavior has been tested for sensitive actions.
• [ ] Headless stdout, stderr, timeout, and retry behavior have been recorded.
• [ ] ACP session creation, cancellation, and error propagation have been tested.
• [ ] Logs can identify the profile, workspace, task, and result.
• [ ] A failed run can be reproduced without guessing which mode was used.
• [ ] The team has named a primary entry, a fallback entry, and prohibited scenarios.
• [ ] The first rollout can be reversed without changing the existing workflow.

The strongest conclusion is conditional, not universal:

• Primary entry: Web for interactive development and approval-heavy work.
• Primary automation entry: Headless for bounded scripts, one-shot tasks, and CI.
• Integration entry: ACP for clients that genuinely need session and event control.
• Fallback: Web for diagnosing ambiguous failures; Headless for isolating a task from an ACP client.
• Prohibited shortcut: Do not use Headless for high-risk writes without an external gate, and do not introduce ACP without a tested client lifecycle.

For a temporary or experimental setup, renting a Mac environment through RUVCLOUD can be more practical than buying hardware, managing remote access yourself, and keeping a separate machine patched while the DeepSeek Harness workflow is still in developer preview. Self-hosting adds hardware ownership, access control, maintenance, and idle-capacity costs; a general-purpose cloud environment may also miss the macOS-specific workspace and remote interaction needs. Once the mode is proven and the workload becomes continuous, a dedicated purchase may be easier to justify. For short trials, parallel mode testing, or a remote validation environment, review the RUVCLOUD ordering options after the runtime policy is defined.