Drive9 for DeepSeek Harness

Persistent agent workspaces and durable, bounded tool evidence for DeepSeek Harness.

@drive9/drive9-dsh is a standard DSH bundle with four independent Cordis components:

• a Drive9 revision-CAS filesystem for Harness read, write, and edit tools;
• an isolated evidence backend for oversized tool results;
• model-visible result_search and result_read tools with hard output limits;
• a model-visible runtime-context warning for the opt-in eventual mount profile.

The architecture keeps four lifecycles separate:

| Layer | Owner | | --- | --- | | Agent loop | DeepSeek Harness | | Session and conversation history | DeepSeek Harness | | Persistent workspace and immutable evidence | Drive9 | | Shell, sandbox, language servers, and compute runtime | the user's DSH deployment |

The Drive9 mount only exposes the persistent workspace inside an existing runtime. It does not create, own, or keep that runtime alive. Evidence remains readable after the runtime or workspace disappears because it is stored under a separate, unmounted Drive9 root.

Drive9 does not provide a shell or sandbox. V1 exposes two explicit mount-consistency profiles:

• strong (default and recommended) uses a Linux Drive9 FUSE mount in the same execution world as Harness process tools. Startup proves SDK-to-mount and mount-to-SDK coherence, and writes wait for exact mounted bytes before returning.
• eventual is an opt-in WebDAV profile. Model-facing reads, writes, revision CAS, and evidence still use the Drive9 SDK, but process tools may observe stale mounted bytes for more than 30 seconds after an SDK write.

The integration never silently downgrades strong to eventual. In real macOS WebDAVFS validation, the Drive9 bridge observed an SDK write immediately while the mounted open/stat view remained stale or blocked for more than 30 seconds.

Why

Agent work has two different kinds of state:

model filesystem tools ── Drive9 SDK + revision CAS ── persistent workspace
                                  │
process tools ── /mnt/drive9 ─────┘

large tool output ── isolated Drive9 evidence root ── exact result_id
                                                   ├─ result_search
                                                   └─ result_read

The workspace remains process-visible, while evidence stays outside the workspace mount. A shell command, workspace deletion, or workspace rollback cannot address the evidence namespace.

Prerequisites

• Linux with Node.js 22.19 or newer, npm, and pnpm on PATH;
• DeepSeek Harness 0.1.0-rc.6, including the standard dsh CLI;
• a current Drive9 CLI with drive9 token issue support and access to a Drive9 server;
• /dev/fuse and fusermount3 for the recommended strong profile, or a WebDAV mount for the opt-in eventual profile;
• separate, path-scoped workspace and evidence credentials. An owner credential is needed only to create roots and issue those scoped credentials.

Install the Harness CLI and pnpm before continuing:

npm install --global @deepseek-ai/[email protected] pnpm

Install the Drive9 CLI from the public Drive9 repository and verify both CLIs:

dsh --version
drive9 version

Quick start

Supply the owner credential through your normal secret injector, then configure the non-secret paths once. The assertion fails before provisioning if the secret is absent:

: "${DRIVE9_OWNER_API_KEY:?inject the Drive9 owner credential}"

export DRIVE9_BASE_URL="https://api.drive9.ai"
export DRIVE9_EVIDENCE_BASE_URL="$DRIVE9_BASE_URL"
export DRIVE9_MOUNT_ROOT="/mnt/drive9"
export DRIVE9_REMOTE_ROOT="/workspace"
export DRIVE9_EVIDENCE_ROOT="/evidence/dsh"
export DRIVE9_MOUNT_CONSISTENCY="strong"

1. Provision isolated roots and credentials

Create both roots once. Keep the evidence root unmounted so workspace tools and shell commands cannot address it:

drive9 ctx add \
  --name dsh-owner \
  --server "$DRIVE9_BASE_URL" \
  --api-key "$DRIVE9_OWNER_API_KEY"
drive9 ctx use dsh-owner

drive9 fs mkdir :/workspace
drive9 fs mkdir :/evidence/dsh

drive9 token issue dsh-workspace \
  --ttl 24h \
  --allow /workspace:read,list,write,delete \
  --print

drive9 token issue dsh-evidence \
  --ttl 24h \
  --allow /evidence/dsh:read,write \
  --print

Each command prints only the bearer token and saves its local name for later rotation or revocation. Store the printed value in your secret manager without leaving it on disk, then inject the values as distinct credentials. The package rejects a shared credential:

: "${DRIVE9_WORKSPACE_API_KEY:?inject the workspace-scoped credential}"
: "${DRIVE9_EVIDENCE_API_KEY:?inject the separate evidence-scoped credential}"

See credential and deployment guidance for production token scope, TTL, and rotation guidance.

2. Mount the workspace

Mount the workspace into the Harness runtime. The default strong profile requires Linux with /dev/fuse and fusermount3:

mkdir -p "$DRIVE9_MOUNT_ROOT"

DRIVE9_API_KEY="$DRIVE9_WORKSPACE_API_KEY" \
  drive9 mount --mode=fuse --profile=none :/workspace "$DRIVE9_MOUNT_ROOT"

The mount must exist in the same execution world as Harness subprocesses. If Harness runs inside a container, mount Drive9 inside that container or bind the mount into it before Harness starts.

--profile=none is part of the strong profile. A coding-agent mount profile can route process paths through a local overlay while SDK calls still address Drive9, splitting the two sides of the revision-CAS contract. Do not use a local-overlay profile, and do not disable the startup proof to make one start.

To opt into relaxed WebDAV semantics instead, mount with WebDAV and explicitly select eventual:

DRIVE9_API_KEY="$DRIVE9_WORKSPACE_API_KEY" \
  drive9 mount --mode=webdav --profile=none :/workspace "$DRIVE9_MOUNT_ROOT"

export DRIVE9_MOUNT_CONSISTENCY="eventual"

This profile returns from writes after the SDK CAS commits; it does not wait for the mounted path to converge. Do not use it for workflows that write through Harness and immediately validate with cat, rg, tests, a language server, or another subprocess.

3. Install the bundle

The recommended release channel is the prebuilt npm package:

dsh plugin --profile web add @drive9/drive9-dsh

To validate an unreleased checkout or install before registry publication, build the same prebuilt tarball from the public repository instead of installing the TypeScript sources directly from Git:

git clone https://github.com/drive9-ai/drive9-dsh.git
cd drive9-dsh
npm ci
PACKAGE_TARBALL="$(npm pack --silent)"
dsh plugin --profile web add "$PWD/$PACKAGE_TARBALL"
cd ..

This source-build route runs the package's normal prepack build and gives DSH a tarball containing dist/. A direct github:drive9-ai/drive9-dsh dependency does not contain built output and is not a supported install path.

The package declares a DSH bundle, so the standard dsh plugin command installs it and adds its cordis.patch.yml layer to the selected profile. The bundle disables the stock fs-sandbox and spill-local storage providers, then installs the Drive9 filesystem, evidence backend, and result tools. Harness's stock filesystem tools, subprocess runtime, sandbox policy, observation policy, and spill policy remain in place. The Drive9 filesystem implements the same per-call read-only, workspace-write, and danger-full-access mutation policy that the replaced filesystem provider enforced.

4. Configure and run

cd "$DRIVE9_MOUNT_ROOT"
dsh web --dump-config
dsh web

dsh web --dump-config is the recommended preflight. Its composed tree must contain exactly one active fs provider: @drive9/drive9-dsh/filesystem. Custom profiles use the equivalent dsh --profile <name> --dump-config and dsh --profile <name> commands; no Drive9-specific launcher is required.

To remove the bundle and its profile layer:

dsh plugin --profile web remove @drive9/drive9-dsh

In the default strong profile, startup fails instead of falling back or weakening the contract when:

• the mount is missing or not writable;
• the remote root is missing or not a directory;
• SDK writes do not appear through the mount;
• mount writes do not produce a newer Drive9 revision through the SDK.

The eventual profile still validates the local mount directory and remote Drive9 root, logs a prominent warning, adds the same warning to the model's durable runtime-context snapshot, and skips the bidirectional proof by default. Explicitly setting verifyCoherence: true still runs the complete proof and propagates any failure.

Components

@drive9/drive9-dsh/filesystem

Drive9FileSystem implements the complete Harness FileSystem contract.

| Operation | Drive9 behavior | | --- | --- | | resolve | Canonical mount resolution with lexical and symlink escape rejection | | processPath / fileUrl | Authenticated provider targets mapped below the real mount | | stat | Drive9 metadata; revision becomes an opaque Harness version | | readText / streamText | Strict UTF-8, NUL rejection, no silent binary coercion | | readBytes | Metadata preflight plus bounded range read | | listDir | Stable sorting and batchStat requests capped at 256 paths | | guarded write/edit | Exact Drive9 revision CAS | | unconditional write/edit | Bounded read/modify/CAS retry | | mutation policy | DSH per-call sandbox policy, rechecked against the fresh canonical target |

In strong, ordinary success returns only after the SDK write commits and the mounted path exposes the same bytes. If Drive9 commits but the mount cannot be confirmed before the bounded coherence deadline, the operation throws DRIVE9_WORKSPACE_COMMITTED_MOUNT_UNCONFIRMED with workspaceCommitted: true, the committed version, and reason timeout, aborted, or io. This is neither success nor evidence that the write did not happen; callers must inspect/reconcile rather than blindly retrying. In eventual, it returns after the SDK CAS succeeds; processPath() and fileUrl() remain available, but their mounted view has no read-your-writes guarantee. Both methods reject targets not authenticated by that filesystem instance.

@drive9/drive9-dsh/evidence

Drive9EvidenceStore implements Harness SpillStore:

1. generate a random 256-bit capability;
2. create the content object;
3. create the canonical manifest with byte count and SHA-256;
4. publish result_id and a provenance receipt only after both writes succeed.

Reads verify stable revisions, exact byte count, manifest shape, SHA-256, and strict UTF-8. A failed manifest write returns no locator. The unreachable content orphan can be reclaimed by operator retention without exposing partial evidence to the model.

@drive9/drive9-dsh/result-tools

The bundle registers:

result_search(result_id, query, max_matches?, context_lines?)
result_read(result_id, offset?, limit?)

Both tools require an exact locator already issued into the current session's durable tool history, or inherited from its explicitly seeded direct parent. Guessing, enumeration, plain-text echoes, unseeded parent references, and sibling references are denied.

Hard package limits:

• 1,000 returned lines;
• 64 KiB returned UTF-8 text;
• 100 search matches;
• 64 MiB scanned per request;
• 64 KiB search query.

Configuration

The shipped bundle reads these environment variables:

| Variable | Required | Default | Purpose | | --- | ---: | --- | --- | | DRIVE9_BASE_URL | no | Drive9 SDK default | Drive9 API base for workspace SDK calls | | DRIVE9_WORKSPACE_API_KEY | yes | — | Workspace-scoped SDK credential | | DRIVE9_MOUNT_ROOT | no | /mnt/drive9 | Process-visible Drive9 mount | | DRIVE9_REMOTE_ROOT | no | / | Remote subtree represented by the mount | | DRIVE9_MOUNT_CONSISTENCY | no | strong | strong Linux FUSE or explicit eventual WebDAV semantics | | DRIVE9_EVIDENCE_BASE_URL | no | DRIVE9_BASE_URL | Drive9 API base for evidence | | DRIVE9_EVIDENCE_API_KEY | yes | — | Separate evidence-scoped credential | | DRIVE9_EVIDENCE_ROOT | no | /evidence/dsh | Unmounted evidence root |

Programmatic composition is also supported inside a DSH context that already provides the standard sandboxPolicy, systemPrompt, and tools services:

import { Context } from '@deepseek-ai/cordis'
import * as Drive9Dsh from '@drive9/drive9-dsh'

const ctx = new Context()

await ctx.plugin(Drive9Dsh, {
  filesystem: {
    mountRoot: '/mnt/drive9',
    remoteRoot: '/workspace',
    baseUrl: process.env.DRIVE9_BASE_URL,
    apiKey: process.env.DRIVE9_WORKSPACE_API_KEY,
    mountConsistency: 'strong',
  },
  evidence: {
    root: '/evidence/dsh',
    baseUrl: process.env.DRIVE9_BASE_URL,
    apiKey: process.env.DRIVE9_EVIDENCE_API_KEY!,
  },
  resultTools: {
    maxScanBytes: 16 * 1024 * 1024,
  },
})

The preset rejects missing credentials and rejects using the same credential for workspace and evidence.

Errors

Filesystem failures use Harness FS_* codes, including FS_STALE_VERSION, FS_NOT_OBSERVED, FS_PERMISSION_DENIED, FS_TOO_LARGE, FS_NOT_TEXT, FS_ABORTED, and FS_IO_ERROR.

DRIVE9_WORKSPACE_COMMITTED_MOUNT_UNCONFIRMED is the distinct post-commit outcome for a strong-profile mount verification failure. It carries workspaceCommitted: true and must never be treated as a retry-safe “write did not happen” error.

Evidence retrieval uses stable DRIVE9_RESULT_* codes:

• DRIVE9_RESULT_INVALID_ID
• DRIVE9_RESULT_NOT_FOUND
• DRIVE9_RESULT_CORRUPT
• DRIVE9_RESULT_UNAUTHORIZED
• DRIVE9_RESULT_SCAN_LIMIT
• DRIVE9_RESULT_ABORTED
• DRIVE9_RESULT_IO

Errors never include credentials or authorization headers.

Security model

• Workspace and evidence credentials must be distinct and path-scoped.
• Evidence has no path, listing, mount, or filesystem-target API.
• Locators are random capabilities but are not authorized by possession alone.
• A versioned issuance receipt, immutable manifest, and enclosing Harness tool event must agree on session, tool name, call id, locator, and manifest digest.
• Current-session and explicitly seeded direct-parent evidence are readable; sibling and unseeded artifacts are not.
• V1 is append-only from the integration's perspective. Configure Drive9 retention or administrative GC for the evidence root.

See SECURITY.md and the complete V1 design lock.

Limits

V1 intentionally does not provide:

• a shell, process sandbox, terminal, or language server;
• automatic Drive9 mounting;
• strong subprocess read-your-writes through WebDAV;
• local-overlay support for either consistency profile;
• LayerFS checkpoints or workspace rollback;
• source-streaming or crash-recoverable tool capture;
• exactly-once external tool side effects;
• evidence enumeration.

The stock Harness spill policy receives a fully materialized tool result. Storage is durable-before-reference, but tool output is not streamed to Drive9 at source in V1.

Development

npm ci
npm run check
npm test
npm run test:race
npm run build
npm pack --dry-run

The default suite includes a scripted real Harness agent loop: the model uses the stock filesystem tool, /bin/cat reads the same mounted bytes, an oversized result is spilled, and later model steps invoke result_search and result_read.

For a real Drive9 service and Linux FUSE mount created with drive9 mount --mode=fuse --profile=none:

DRIVE9_REAL_E2E=1 npm run test:real

Required environment and cleanup behavior are documented in docs/operations.md. See CONTRIBUTING.md for the release checklist. The real test rejects non-Linux and non-FUSE mount roots.

Compatibility

| Component or profile | Supported contract | | --- | --- | | Node.js | 22.19 or newer | | DeepSeek Harness | 0.1.0-rc.6 | | Drive9 JavaScript SDK | 0.1.4 | | strong | Linux Drive9 FUSE; writes wait for exact process-visible bytes. Current real-service validation observed SDK-to-mount convergence in 1.3–1.5 seconds and mount-close-to-new-SDK-revision convergence in 0.36–0.40 seconds. These observations are not an SLA. | | eventual | WebDAV; no subprocess read-your-writes guarantee, with observed staleness beyond 30 seconds. |

DeepSeek Harness is a developer preview. Upstream service-contract changes require a new package release and contract review.