ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness Workspace: Path, Project ID, Sandbox Root

Concepts & ArchitecturePublished 2026-11-18Author: DeepSeek Plugin Market
DeepSeek HarnessDSH pluginworkspacesandboxworking directory
A DeepSeek Harness workspace is a visible path, a project identity, and a sandbox write root. Separate them to explain writes failing on a correct-looking path.

“Workspace” in DeepSeek Harness is at least three identities: the directory path you see, the project identity used for session ownership, and the sandbox write root used for permissions. The official working-directory docs are explicit: it provides user context and an execution path without changing the original project identity, sandbox write root, or existing process directories (source). Mixing them produces “the path is right but writes fail” and “I switched directories but the session still belongs to the old project.”

DeepSeek Harness: Three identities, not one path

Each identity answers a different question: where, whose, and what may be written. The split (source):

IdentityQuestionUsed by
Directory pathWhere is the project?UI, config, user actions
Project identityWhich project owns the session?Session ownership, recovery, archive
Sandbox write rootWhere may the agent write?Sandbox, approval, executor

Many “workspace problems” treat the three as one value. A changed path is assumed to change identity; a path inside the project is assumed to be writable.

They can align or diverge. When aligned, life is easy; when not, know which layer each action reads.

DeepSeek Harness: Directory path: the visible project

The path is the outer layer and the easiest to change. Selecting a directory in the UI, cd in a shell, or writing an absolute path in config all change this layer. (source)

Its job is to tell the system and the user where the project is. It affects display, selection, and the launch location, but it does not decide session ownership or widen writes.

Three common variants: absolute, relative, and symlink. A relative path depends on the current directory; a symlink points at a real path. Both can produce “same-looking directory, different resolution.”

Use absolute paths in config and sessions. For symlinks, confirm the resolved real path is inside the sandbox write root.

DeepSeek Harness: Project identity: ownership and recovery

Project identity is “which project this session belongs to,” not “where the project lives.” The working directory does not change the original identity, so moving or switching directories should not re-home a session (source).

It matters in three places:

  1. Session ownership — lists, archive, and recovery group by project.
  2. Workspace records — session ids and pinned order live there.
  3. Recovery — reopening a project finds its sessions.

If identity is rewritten, the symptom is “the session exists but belongs to another project” or “the workspace no longer shows it.” Check records before deleting data.

Identity is more stable than the path but not immutable. Copying a project, renaming a directory, or moving machines can create a new identity; treat that as a migration, not “same path, same project.”

DeepSeek Harness: Sandbox write root: the permission boundary

The sandbox write root is what permissions compare; the path string is only its display. A working directory can provide an execution path, but permission checks use the sandbox root, so a correct-looking path can still fail (source).

Three common mismatches:

  • Working directory inside, root elsewhere — reads work, writes are denied.
  • Symlink points outside — looks inside, writes outside.
  • Case or normalization differences — Windows and case-insensitive filesystems can compare differently.

The sandbox root also pairs with the permission preset. workspace-write limits writes to the workspace and asks on overflow; a wider preset changes the root, not the working directory.

For “correct path, write denied,” check the preset, then the sandbox root, then the resolved real path. All three beat reading the UI path.

DeepSeek Harness: What changes when the working directory changes

The execution path changes; the project identity, sandbox write root, and existing process directories do not. The official docs state the boundary (source).

ObjectAfter a working-directory change
Current execution pathChanges
Original project identityUnchanged
Sandbox write rootUnchanged
Existing process directoryUnchanged

Two symptoms follow: switching into a subdirectory keeps the session in the original project; switching outside may allow reads but not writes beyond the original root.

Existing process directories stay put: a shell already running does not change when you switch. New commands may use the new directory while old processes stay in the old one; distinguish “new command” from “already running.”

If you need a different write scope, change the permission preset or sandbox config, not only the working directory. A directory change moves execution, not permissions.

DeepSeek Harness: Three failure examples

Each example maps to one identity mismatch. Use the symptom to find the layer (source):

  1. Sessions disappeared after switching — identity did not change, but the UI filters by the new path; return to the original project or look up by identity.
  2. Correct path, write denied — the sandbox write root differs from the current path; check the preset and the resolved path.
  3. Workspace list empty — the workspace record is damaged or unmounted; session files may still exist, so back up before repair.

The shared rule is “do not delete data first.” Workspace records, project identity, and session logs are three layers; deleting one can make the other two unrecoverable.

Verify with a read-only task, a write task, and a directory switch: reads work, writes land where expected, and session ownership does not change unexpectedly. All three mean the identities align.

The existing dsh-workspace-explained covers the concept, develop-workspace-package covers package structure, and fix-workspace-disappeared covers record repair; this article separates the three identities. Path is entry, identity is ownership, write root is permission; none replaces another.

Once the three align, workspace problems stop being mysterious: every symptom points to one layer.

Three identities, three questions; do not answer one with another.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Are the DeepSeek Harness workspace path and project identity the same?

DeepSeek Harness does not work that way. The DeepSeek Harness workspace path is the visible directory; the project identity is used for session ownership and recovery. Changing the working directory does not change the original identity.

Does the DeepSeek Harness sandbox write root follow a working directory change?

In DeepSeek Harness, not automatically. A DeepSeek Harness working directory provides user context and an execution path; the original project identity, sandbox write root, and existing process directories stay unchanged.

Why can a DeepSeek Harness write fail when the path looks correct?

In DeepSeek Harness, the sandbox write root may differ from the visible path. DeepSeek Harness permission checks compare the sandbox root, not the string in the UI, so a correct-looking path can still be out of scope.

Does a DeepSeek Harness workspace disappearing delete session data?

DeepSeek Harness usually does not work that way. DeepSeek Harness stores workspace records and session data separately; a broken or unmounted record can make the UI look empty while files remain on disk.

Related Terms

workspace path
A workspace path is the visible DeepSeek Harness project directory used for display and selection, not the project identity or the sandbox write root.— DeepSeek Harness reference - Workspace
project identity
Project identity is the stable DeepSeek Harness value used for session ownership and recovery; changing the working directory does not change it.— DeepSeek Harness reference - Working directory
sandbox write root
The sandbox write root is the path range DeepSeek Harness permissions actually compare, deciding which writes are allowed or need approval.— DeepSeek Harness reference - Working directory
working directory
A working directory provides DeepSeek Harness user context and an execution path without changing the original project identity, sandbox root, or existing process directory.— DeepSeek Harness reference - Working directory

Sources