DeepSeek Harness Portable

Your complete AI coding workspace—portable across Windows, Linux, and macOS.

Run the official DeepSeek Harness from one self-contained folder on an internal disk, USB drive, or external SSD. Your runtimes stay isolated by operating system while chats, settings, skills, plugins, and credentials travel with you.

Download latest release · Watch walkthrough · Quick start · How portability works · Troubleshooting

Video walkthrough

▶ Watch the complete walkthrough on YouTube

DeepSeek Harness normally depends on a local Node.js environment and stores host-specific paths. This project wraps the official Harness distribution with a portable bootstrap that keeps installation, updates, runtime dependencies, and cross-platform session migration inside one folder.

Download deepseek-harness-portable.zip, extract it, and run the launcher for the current operating system.

windows.bat setup
windows.bat

sh linux.sh setup
sh linux.sh

sh mac.sh setup
sh mac.sh

The first command initializes or repairs only the current platform. The second starts the local DeepSeek Harness web interface and opens it in your normal browser, typically at http://127.0.0.1:3080.

Every launcher exposes the same interface:

Examples:

sh mac.sh doctor
sh linux.sh portable-update
sh mac.sh -- --profile headless "summarize this project"

windows.bat doctor
windows.bat -- --help

Each operating system receives a separate runtime and cache. Initializing macOS never downloads Windows or Linux assets; those are added only when their launcher runs.

Deepseek-Harness-Portable/
├── windows.bat
├── linux.sh
├── mac.sh
├── data/          shared Harness home, sessions and settings
├── models/        preserved model files
├── runtimes/      isolated windows-x64, linux-x64 and macos-arm64 runtimes
├── packages/      downloads and package-manager caches
├── scripts/       bootstrap, migration, diagnostics and reset logic
├── state/         per-platform installation state
├── logs/          portable launcher logs
└── temp/          staging and temporary files

The repository root intentionally contains only the three launchers. Everything else is organized by function.

DeepSeek Harness stores absolute workspace paths inside its registry, projection cache, session directory names, and compressed chat headers. Those paths are different on Windows, Linux, and macOS.

Before Harness starts, the portable launcher:

1. Detects paths belonging to another operating system.
2. Relocates workspaces that live inside the portable folder.
3. Rewrites only the session-header frame while preserving every compressed chat event.
4. Moves the session to the correct operating-system-specific directory key.
5. Synchronizes the workspace registry and projection cache.
6. Keeps an untouched backup before rewriting a session log.

If an external project is unavailable on the current computer, its chat history is attached to a fallback under data/portable-workspaces/ so the conversation remains viewable. To edit the same project everywhere, keep its project files inside that portable workspace as well.

• Downloads are written to staging locations and checked with SHA-256 before promotion.
• An interrupted installation does not replace the previous working runtime.
• Symlinks are avoided for exFAT compatibility.
• Spaces and Unicode characters in the folder path are supported.
• Moving or renaming the folder does not change system configuration.
• Browsers are launched with the host user environment, preventing portable paths from interfering with the macOS Keychain or browser profile.

Installed copies check for a tested portable release at most once every 24 hours. Network or update failures leave the current runtime active.

The repository automation checks the DeepSeek Harness npm update channel once per day. A candidate is published only after it:

1. Generates an exact dependency lock.
2. Runs the vulnerability audit.
3. Performs clean installations on every supported platform.
4. Runs contract, doctor, CLI, session-portability, and smoke tests.
5. Publishes the release archive, checksums, and build provenance.

Disable launcher-side update checks in a controlled environment with:

export DSH_PORTABLE_NO_AUTO_UPDATE=1

Reset removes runtimes, sessions, settings, credentials, caches, downloads, logs, temporary files, and installation state. It preserves models/, the immutable launchers, reset tools, bootstrap logic, and signed manifests required to reinstall.

scripts\reset.bat

sh scripts/reset.sh

Both reset implementations require confirmation before removing portable data.

• Keep the drive physically secure.
• Use provider keys with budgets or spending limits.
• Never publish a fully initialized test archive containing data/.
• Do not commit data/, state/, runtimes/, caches, or model files.
• Revoke any credential that has been exposed in a terminal recording, screenshot, chat, or public repository.
• Verify public downloads with the release SHA256SUMS file and GitHub build provenance.

Cloud models still require network access and valid provider credentials. After initialization, the Harness core can start offline, but cloud inference and optional downloads cannot.

For deeper diagnostics, run the platform launcher with doctor and review data/dsh-home/logs/.

Every source change is tested through GitHub Actions on:

• Windows Server 2022 x64
• Ubuntu 22.04 x64
• Ubuntu 24.04 x64
• Apple Silicon macOS

The suite covers manifest integrity, clean installation, launcher behavior, runtime isolation, checksum validation, chat-path migration, multi-frame Zstandard history preservation, and CLI startup.

View the cross-platform test history →

This project packages the official @deepseek-ai/dsh distribution. DeepSeek Harness itself is maintained in deepseek-ai/deepseek-harness.

This repository is an independent portability layer and is not the upstream DeepSeek Harness project.