DeepSeek Harness

DeepSeek Harness (dsh) is a plugin-based agent harness on Cordis. @struktoai/mirage-dsh gives dsh one Mirage workspace as its filesystem and shell, so its tools work on whatever the workspace mounts: S3, Slack, Gmail, Postgres, disk.

Install

npm install @struktoai/mirage-dsh @struktoai/mirage-node @deepseek-ai/cordis @deepseek-ai/dsh-fs @deepseek-ai/dsh-fs-patch @deepseek-ai/dsh-shell @deepseek-ai/dsh-spill @deepseek-ai/dsh-subprocess

What is wired to what

Mirage plugin	dsh service	Used by
`MirageService`	`ctx.mirage`	The one workspace the plugins below share
`MirageFileSystem`	`ctx.fs`	`read`, `write`, `edit`, `apply_patch` and the working directory
`MirageShellExecutor`	`ctx.shell`	`bash`
`MirageSubprocess`	`ctx.subprocess`	Tools that start a program by argv
`MirageSpillStore`	`ctx.spillStore`	Large tool results, saved as workspace files the agent can read back

The agent starts in the disk mount that holds the directory dsh was launched from, or in /. The working_directory tool moves between mounts.
Each bash call is a fresh shell. Give MirageShellExecutor a sessionId to keep exports and functions between calls.
Mount modes and session profiles apply to every tool. DSH_PERMISSION_MODE=read-only makes every mount read-only.
An ask rule shows in dsh’s approval prompt. With no prompt, the line is refused and the question stays pending: answer it through ctx.mirage.decisions, then run the line again.

import { Outcome, Scope } from '@struktoai/mirage-core'

for (const waiting of ctx.mirage.decisions.pending()) {
  await ctx.mirage.decisions.answer(waiting.id, Outcome.ALLOW, Scope.ONCE)
}

Example

import { Context } from '@deepseek-ai/cordis'
import { DiskVFS, MountMode, RAMVFS, SlackVFS, Workspace } from '@struktoai/mirage-node'
import {
  MirageFileSystem,
  MirageService,
  MirageShellExecutor,
  MirageSpillStore,
  MirageSubprocess,
} from '@struktoai/mirage-dsh'

const ws = new Workspace({
  '/project': [new DiskVFS({ root: process.cwd() }), MountMode.WRITE],
  '/slack': [new SlackVFS({ token: process.env.SLACK_BOT_TOKEN ?? '' }), MountMode.READ],
  '/tmp': [new RAMVFS(), MountMode.WRITE],
})

const ctx = new Context()
await ctx.plugin(MirageService, { workspace: ws }).await()
await ctx.plugin(MirageFileSystem).await()
await ctx.plugin(MirageShellExecutor).await()
await ctx.plugin(MirageSubprocess).await()
await ctx.plugin(MirageSpillStore).await()

const run = await ctx.shell.execute(ctx.shell.resolve({ command: 'grep -rl invoice /slack /project' }))
console.log((await run.result()).stdout.text)

examples/typescript/agents/dsh/dsh.ts is a longer runnable version, with Python and permissions.

Use a workspace on a Mirage server

Give MirageService a remote instead of a workspace and the plugins call the workspace a Mirage server holds: each bash line goes to its shell, each file call to its VFS API. dsh can then run where nothing is mounted, such as a Cloudflare Worker. Import from @struktoai/mirage-dsh/remote there, which leaves out @struktoai/mirage-node:

import { Context } from '@deepseek-ai/cordis'
import {
  MirageFileSystem,
  MirageService,
  MirageShellExecutor,
  MirageSpillStore,
} from '@struktoai/mirage-dsh/remote'

const ctx = new Context()
await ctx.plugin(MirageService, {
  remote: { url: 'https://mirage.example.com', workspace: 'ws_123', token: process.env.MIRAGE_TOKEN },
}).await()
await ctx.plugin(MirageFileSystem).await()
await ctx.plugin(MirageShellExecutor, { sessionId: 'agent' }).await()
await ctx.plugin(MirageSpillStore).await()

The server owns the mounts, machines and profiles. sessionId names a session on the server, created on first use.
The plugins make no sandbox claim, so DSH_PERMISSION_MODE=read-only does not narrow a remote workspace. Give the session a read-only profile on the server instead.
Asks are answered on the server, at /v1/workspaces/{id}/asks.
MirageSubprocess needs a workspace in the same process.
ctx.mirage.explain asks the server’s ?explain=true, so it works only where the server serves it.

Use with the dsh CLI

The package is also a dsh bundle. Added to a profile, it replaces dsh’s filesystem, shell, subprocess and spill providers with the Mirage ones:

dsh plugin --profile web add @struktoai/mirage-dsh
dsh --profile web

The bundle mounts one RAM disk at /tmp. Set your own mounts, Python and permissions in the profile’s cordis.patch.yml. Python runs only on an exec mount:

- id: mirage
  config:
    mounts:
      /tmp: { vfs: ram, mode: exec }
      /project: { vfs: disk, mode: exec, config: { root: . } }
      /slack: { vfs: slack, mode: read, config: { token: !!js process.env.SLACK_BOT_TOKEN } }
    machines:
      py: { provider: in_process, runtime: monty, captures: [python, python3] }
    profiles:
      agent:
        commands:
          ask:
            - { commands: [rm], reason: deletes are reviewed }
          deny:
            - { commands: [git push], reason: no publishing }
    profile: agent

PowerShell and the glob and grep tools stay off, since they start programs on the host. The agent searches with rg, grep and find in bash.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes