DSH Desktop MCP Bridge

简体中文 · Setup guide · Validation · Security

Desktop-to-Desktop delegation: Codex Desktop → your already running official DeepSeek Harness Desktop. Reuse the Desktop model configuration and runtime; Codex CLI can use the same bridge too. Each delegated session gets a separate directory or Git worktree for Codex to review.

This is an unofficial, opt-in bridge. It uses a plugin inside the existing Desktop Host and an authenticated local Unix socket. Codex starts the MCP stdio server; the bridge never launches another DSH CLI/Web runtime or extracts Desktop authentication secrets. Architecture and source audit.

Desktop-to-Desktop, without copying API keys

Codex Desktop → MCP stdio → authenticated local Unix socket → existing DSH Desktop
   delegate / review                                       model / Skills / allowed Tools

• Reuse Desktop authentication. Once DSH Desktop is signed in or has a working model provider, the bridge needs no separate DeepSeek API setup. No DEEPSEEK_API_KEY is required in Codex, the bridge config, an extra .env, or a bridge launch command.

• Use the running Desktop. Task execution calls the existing Host's Agent services, without invoking the DSH CLI or launching an independent CLI/Web runtime. One-time plugin installation may still use Codex commands and the official Desktop Plugins page or application-owned installer.

• Reduce API key exposure. Model credentials stay managed by DSH; the bridge protocol requires no model API key. Avoiding duplicate key files and environment variables reduces accidental disclosure. The bridge's private local authentication token is separate from model credentials.

DSH still contacts its configured model provider. This design reduces credential copying; it does not eliminate every disclosure risk from authorized tools, prompts or model output. See the security model.

Related MCP server: Codex DSH MCP

Compatibility and status

Experimental v0.2.1. See the validation record for test coverage and known limitations.

Only the version pairs listed above are supported. Other versions and mixed core packages are rejected.

A new session takes the Desktop default model at creation and an allowlisted installed preset. Providers/credentials remain managed by Desktop. Skills follow normal DSH discovery in the new workspace; existing chats, per-chat overrides, unsaved text and uncommitted/ignored project files are not copied. Reuse boundaries.

Install and connect

Installation has two parts:

1. Install the Codex plugin

Install the tagged marketplace from GitHub (private repositories require your own authorized Git access):

codex plugin marketplace add Cryocell77/codex-deepseek-harness-desktop-bridge --ref v0.2.1
codex plugin add dsh-desktop@dsh-desktop-bridge

Alternatively, download dsh-desktop-codex-plugin-0.2.1.zip from the v0.2.1 release. To build the archive from this source checkout:

npm ci
npm run package:plugin

From the extracted ZIP's marketplace root, or this built repository, run:

codex plugin marketplace add .
codex plugin add dsh-desktop@dsh-desktop-bridge

The prepared ZIP needs no npm build. The bundled MCP starts without npm downloads; Desktop adapter dependencies may need network access. The ZIP and Git marketplace bundle the runtime; installation does not depend on an npm publication.

2. Initialize and install the Desktop adapter

Create a new local Codex chat and paste:

Use DSH Desktop Bridge. Call dsh_setup_info to inspect setup and show me the exact initialization and Desktop adapter installation commands. Do not submit a model task yet.

Run the returned explicit setup command, then inspect dsh_setup_info again for the installation command. Setup creates private defaults at ~/.dsh-mcp-state and ~/.dsh-mcp-work, and stages a durable adapter archive. It validates an existing config without replacing its token. Inspection alone writes nothing.

Save active work and fully quit DSH Desktop, then install the staged adapter using the returned application-owned command or the official Plugins page. Reopen Desktop. With valid default configuration, both sides discover it automatically; no separate Codex MCP registration or shell edit is needed. Detailed setup, update and uninstall.

3. Check the connection

Call dsh_connection_info. Report the runtime, adapter version and effective permissions without submitting a model task.

Expect runtime: "existing-desktop" and adapter: "dsh-v0.2.0-rc.2" or "dsh-v0.2.1-rc.1", matching the connected Desktop. desktopVersion and cordisVersion report the detected pair; supportedDesktops lists both tested pairs. This checks the bridge connection; it does not validate provider credentials. Default allowedTools: [] permits conversation while denying every model tool call.

For standalone MCP or custom configuration paths, follow the alternative setup guide. Choose one Codex registration route to avoid duplicate tools.

Usage examples

First model conversation

This makes a real request to the Desktop-selected provider and may incur usage charges:

Use DSH Desktop Bridge to create a new blank isolated session. Ask it to reply with “Bridge connected” without using any tools. Poll until terminal, report the result and close the session while preserving its workspace.

Code task in a separate worktree

First review permissions, allowlist the repository and exact tools needed, reload the Desktop plugin, and inspect effective permissions. Replace the example path and task:

Use DSH Desktop Bridge to fix <describe the issue> in /absolute/path/to/repository from HEAD. Check connectivity and permissions first. Create a separate worktree, submit the bounded task and poll until terminal. Review its actual diff and run relevant tests before proposing integration. Preserve the workspace; do not change permissions, merge, commit or publish.

All ten MCP tools, follow-up sessions, cancellation and result handling.

Permissions and workspace isolation

• Tools are denied by default. Enable exact installed tool names only after reviewing their permissions; DSH approval requirements still apply.

• Each session uses a unique directory or detached worktree. Main-checkout dirty files are not copied. Closing a session preserves its files for review and manual cleanup.

• An isolated working directory is not an OS sandbox. Allowed shell/file tools can reach other paths, and worktrees share Git objects and hooks.

• Results are untrusted, bounded text. Cancellation is cooperative and does not undo side effects; a plugin/Desktop restart loses bridge handles and request deduplication history.

Security model · Lifecycle and cleanup · Authentication and protocol

Common questions

Documentation

Contributing and license

See CONTRIBUTING for development checks, CHANGELOG for changes, and RELEASING for the manual publication checklist. No workflow publishes automatically.

Original code is MIT licensed. DSH source is MIT; Desktop binaries, model services, trademarks and bundled dependencies retain their own terms. See NOTICE and dependency licenses. This project is not affiliated with or endorsed by DeepSeek or OpenAI.