Introduction

Agent developers using DeepSeek Harness (DSH) for development frequently need to migrate Codex environments across different machines. Manually copying code repositories, configuration files, and database snapshots can easily lead to missing files, and may even unintentionally carry out or leak sensitive credentials (such as .git/config, SSH keys).

dsh-migrate-codex is a DSH plugin that provides a standardized process for securely packaging, verifying, and restoring Codex environments. It ensures that only authorized repositories are migrated and strictly excludes sensitive information during transfer.

Plugin Overview

  • Name: dsh-migrate-codex
  • Maintainer: ChengxiuCDP
  • Category: Workflow
  • License: MIT

Installation and Enablement

Install the plugin under a DSH Profile:

dsh plugin --profile <name> add <repo URL or npm package>

After installation, restart the Profile to make the features take effect.

Core Capabilities

This plugin provides the following command-line capabilities, along with a companion Skill to guide the agent in understanding the workflow:

  1. Package environment: /migrate-codex prepare <dir>
    Package whitelisted repositories and dirty snapshots into a directory.

  2. Verify integrity: /migrate-codex verify <dir>
    Check SHA256SUMS checksums, Bundle integrity, and credential exclusions for compliance with security standards.

  3. Restore environment: /migrate-codex restore <dir>
    Restore the packaged environment to a new machine. If the target path already exists, the command aborts execution to avoid overwriting.

  4. Restore a single worktree: /migrate-codex restore-worktree <dir> <slug>
    Rebuild a specific dirty worktree on demand.

  5. Skill guidance: Skill codex-migration
    The agent can use this Skill to learn the complete migration workflow, security guardrails, and how to align Codex configuration with DeepSeek Harness.

Usage Example

In a DSH session, you can trigger the process with natural-language instructions or directly call the commands:

# 1. 先进行验证
/migrate-codex verify ~/Desktop/codex-migration

# 2. 验证通过后执行恢复
/migrate-codex restore ~/Desktop/codex-migration

Configuration and Custom Whitelist

The published version of the plugin contains only placeholder examples (such as example-primary). Developers need to configure the actual whitelist.

Environment Variables

  • CODEX_MIGRATE_TABLE: Specifies the path to the whitelist file.
  • CODEX_MIGRATE_MAIN_SLUG: Specifies the slug of the repository that contains worktrees (default is example-primary).

Whitelist File

Define the actual whitelist in the bin/whitelist.local.tsv file. This file should usually be added to .gitignore to prevent it from being committed.

The file format is TSV, and each line contains four columns: slug, role, source-path, and required.

Sample content:

my-main-repo    primary ~/my-main-repo  yes

Security Design

The plugin follows these security principles by design:

  • Whitelist mechanism: Only explicitly whitelisted repositories are migrated.
  • Zero credential leakage: Git bundles only transfer commit history and never include .git/config, so remote credentials are not carried out from the source machine.
  • Integrity verification: SHA256SUMS checks are performed after all files are transferred.
  • Credential exclusion: Automatically excludes auth.json, .env*, private keys, certificates, and SQLite files.
  • Idempotence and atomicity: Restore operations abort if the target exists, and a failed operation does not leave a half-restored file system.

Notes

  • The plugin runs with the permissions of the current DSH process. It is recommended to inspect the source code before installation.
  • Restore operations do not overwrite an existing target directory, ensuring operational safety.

Summary

dsh-migrate-codex solves the issues of chaotic file management and security risks in cross-machine migration of Codex environments. With the standard prepare-verify-restore workflow, developers can confidently synchronize development environments across different machines.

Plugin Directory | GitHub Repository