DeepSeek Harness Migration to a Cloud Mac in 2026 // NOVAKVM Engineering Blog

A project can appear on the cloud Mac while the model, plugins, or saved sessions still fail.

The fastest safe method is to create a clean, reversible target environment, then migrate the workspace, configuration, credential references, plugins, and session history as separate assets. Do not copy the entire directory blindly, and do not assume an old session will resume across versions.

Last updated August 18, 2026. Current behavior was checked against the official DeepSeek Harness repository, Web UI guide, provider guide, architecture documentation, and Python SDK guide.

This guide is for:

Local users turning a short experiment into a continuously available Agent task.
Agent operators who need auditable sessions and repeatable plugin configuration.
Project owners deciding which state must survive migration and which state should be rebuilt.

[ SECTION_01 ] Why a full-directory copy creates a broken target

DeepSeek Harness is still described as a developer preview, and the official repository warns that compatibility-breaking changes will occur. That warning changes the migration strategy: the durable asset is not one folder. It is a collection of runtime inputs that may have different compatibility requirements. Read the official repository status and run instructions

A common failure looks harmless at first:

The project files are visible.
The Web UI starts.
The workspace can be selected.
The model request fails because the credential reference is empty.
A plugin does not load because its package or runtime is different.
The session list appears, but the selected session points to a path or provider that no longer exists.

The hidden cost is not the file transfer. It is the time spent guessing which layer failed.

Use this asset classification before copying anything:

Asset class	Typical contents	Migration decision	Recovery standard
Project files	Repository, branches, ignored files, local patches	Copy or re-clone, then verify	Agent reads the intended branch and only the intended workspace
Harness configuration	Profile, settings, model defaults, plugin layers	Copy selectively and inspect	The target boots with an equivalent configuration boundary
Secrets	API keys, environment variables, credential references	Re-inject or bind through controlled secret management	A live request succeeds without exposing the secret
Runtime dependencies	Node.js, Python, package manager, plugins, native tools	Rebuild from a recorded manifest	Harness starts without fallback errors or missing modules
Historical state	Session logs, transcripts, approvals, task records	Preserve as backup; test on a copy	Logs remain readable, or a new session is created safely

The official architecture documentation treats the model adapter, tool registry, session log, and Agent loop as separate runtime components. A profile is also a layered composition, not simply a collection of unrelated files. Review the official architecture description

Decision rule: copy reproducible inputs, rebuild environment-dependent inputs, re-inject secrets, and preserve session history separately.

[ SECTION_02 ] Workspace identity and path control

A cloud Mac can contain the right repository and still expose the wrong project to the Agent. This happens when the source uses one absolute path, the target uses another, or the selected workspace points to a parent directory containing several unrelated repositories.

The official Web UI guide states that the dsh process uses its invoking directory as the default filesystem location. It also requires a workspace selection before the session composer becomes available. That makes the launch directory and selected workspace part of the migration record, not incidental details. Check the official Web UI workspace behavior

Before permitting edits or shell commands, record these items from the source Mac:

Absolute project path.
Repository root.
Active branch.
Commit identifier.
Uncommitted files.
Git worktrees or submodules.
Local instruction files used by the Agent.
Build and test commands.
Paths that must remain outside the workspace.

Then prepare the cloud Mac with a clean workspace boundary. Avoid selecting a broad home directory. If the project is obtained through Git, clone the intended branch into a dedicated path. If local uncommitted changes matter, export them as a patch or commit them to a temporary migration branch.

The first cloud task must be read-only:

“List the repository root, active branch, top-level packages, and files modified after checkout. Do not edit files or run commands that change state.”

The task passes only when the output matches the migration record. If the Agent lists a sibling project, sees the wrong branch, or reports a different root, stop there. Opening write access before fixing the path turns a configuration problem into a project-integrity problem.

[ SECTION_03 ] Configuration layers and provider identity

The configuration layer contains more than a model name. Separate these fields before migration:

General settings.
Provider identity.
Provider credential reference.
Model identifier and default selection.
Environment variable names.
Plugin and profile layers.
Workspace and session directory references.

The provider guide confirms that credentials are stored separately from ordinary settings. The Web UI stores the key in $DSH_HOME/.credentials.yaml, while settings retain a credential reference rather than the literal secret. It also states that a custom Provider ID is permanent because saved sessions, model defaults, requests, and credential references use it. Review the official provider and credential guide

This explains a frequent migration error: the target has the same endpoint and model, but the provider was renamed during cleanup. The display label may look equivalent, yet the saved session still refers to the old identity.

Do not casually rename a provider during migration. If a new identity is required, add the new provider, validate it, and keep the old identifier available until the target is accepted. Start a new model request on the cloud Mac. Do not use an old saved conversation as the first model test.

Configuration item	Safe action	Do not do this	Acceptance signal
Non-secret settings	Copy after reviewing paths and defaults	Copy unknown overrides without inspection	Target settings match the approved record
Provider ID	Preserve exactly when old sessions depend on it	Rename only because the display label looks untidy	Existing references resolve
Model default	Re-select and test in a new session	Assume the old default is still installed	A new request reaches the expected model
Credential reference	Recreate the reference on the target	Put a literal key in an archive	Process reads the intended secret source
Environment variables	Recreate names and permissions	Copy shell history or plaintext exports	Runtime sees the variable without logging its value
Profile and plugin layers	Rebuild in the same order	Mix source and target layers at random	`dsh --profile ... --dump-config` shows the intended tree

The architecture guide documents layered boot composition and the --dump-config diagnostic. Use that output as a configuration fingerprint before enabling tasks.

[ SECTION_04 ] API key handling

A DeepSeek Harness API key should not be packaged into a migration archive, committed with a project, or copied into a session backup. The target should receive the secret through a controlled injection method.

The safe pattern is:

Copy the configuration without literal secret values.
Create the target credential reference.
Inject the key through the approved secret channel.
Start the cloud process with the intended environment.
Confirm that the runtime can authenticate.
Inspect logs, terminal history, shell startup files, and delivery materials for accidental residue.
Revoke or rotate the source credential if it was exposed during handling.

The official provider documentation states that the Web UI treats keys as write-only and returns a redacted descriptor after saving. That is a useful operational boundary. The operator should be able to prove that authentication works without printing the secret.

A failed request is not always a bad key. The same guide lists missing credentials, unknown models, and failed model discovery as separate troubleshooting states. Check the active provider, credential reference, model identifier, and endpoint independently.

[ SECTION_05 ] Plugin and runtime reconstruction

Local plugins often fail on a remote environment for reasons unrelated to the plugin source:

The runtime version differs.
A package was installed globally on the source Mac but is absent on the target.
The plugin expects a local binary or shell utility.
A profile loads the plugin in a different order.
A configuration override targets an identifier that changed.
File permissions or executable flags were lost.
The plugin depends on a workspace path that no longer exists.

DeepSeek Harness uses a plugin-oriented architecture. The official documentation describes profiles, bundles, patch layers, model adapters, tools, persistence, sandbox policy, and approval policy as separate parts of the booted tree. Reproducing only the visible plugin folder is therefore insufficient. Use the official profile and bundle reference

Rebuild in this order:

Record the source Harness revision.
Record the runtime versions.
Export the plugin package list.
Record profile names and patch files.
Record required system utilities.
Start with the official base combination.
Add one plugin or layer at a time.
Run the same read-only diagnostic after each addition.
Keep the first failing addition isolated.

If the target cannot reproduce the full source combination, return to the official base profile and complete the basic startup test. Repeated full reinstalls hide the actual incompatibility and make rollback harder.

For an operational migration, the acceptance standard is not “the plugin folder exists.” It is “the plugin loads, exposes the expected capability, respects the approval policy, and does not change the workspace boundary.”

[ SECTION_06 ] Session logs and safe continuation

A saved session is more than a transcript. The official architecture documentation describes the session log as the source from which model history, replay, UI fidelity, forks, transcripts, telemetry, and persistence are derived. Model-visible input must be reconstructable from that log.

The Python SDK guide adds an important implementation detail: the example stores an uncompressed JSONL session log under the configured session directory. It also separates the workspace from the session root. Check the official Python SDK session and directory guide

This means DeepSeek Harness session logs should be treated as a separate migration asset. Keep the original backup unchanged. Test restoration against a copy. Do not overwrite the source log while troubleshooting.

Can a session continue after moving to another Mac? Sometimes the log may be readable, but that does not establish safe continuation. A saved session can refer to:

A Provider ID that no longer exists.
A model that is not configured on the target.
A workspace path that changed.
A plugin capability that is missing.
A runtime state that cannot be reconstructed.
A session format changed by a developer-preview update.

The safest sequence is:

Open or inspect the copied log without modifying the source.
Confirm the provider and model references.
Confirm the target workspace.
Confirm the required plugins.
Attempt read-only continuation.
If any dependency is uncertain, preserve the log for audit and create a new session.

A new session is not a data-loss failure when the historical log remains available. It is often the correct compatibility boundary.

Migration warning: Never use an old session to grant write or shell permissions on the target before confirming its workspace, provider, model, and plugin context.

[ SECTION_07 ] Two migration paths

The following split keeps recovery simple:

Path	Use when	Main action	Result
Reproduce and continue	Same provider identity, compatible runtime, verified workspace, readable log	Restore a copy and test limited continuation	Existing context may be reused after validation
Preserve and restart	Version, plugin, provider, or workspace compatibility is uncertain	Archive the log and begin a new session with a migration summary	History remains auditable without unsafe resume

The second path is usually better for long-running Agent tasks. The operator can place a short migration summary in the new session:

Source commit.
Completed work.
Open tasks.
Known failures.
Relevant session-log location.
Approved workspace path.
Current provider and model.
Plugin set accepted on the target.

This preserves continuity without pretending that every runtime state is portable.

[ SECTION_08 ] Cloud Mac migration procedure

Follow these steps in order.

1. Freeze the source state

Stop active Agent tasks. Record the Harness revision, runtime versions, current branch, commit, uncommitted changes, Provider IDs, model defaults, plugin list, profile layers, workspace path, and session root.

Keep the source Mac available during acceptance. Do not uninstall the source runtime yet.

2. Create the target boundary

Prepare an isolated cloud Mac workspace. Use a dedicated project directory and a separate session directory. The official Python SDK examples require an isolated workspace and support macOS 14 or newer on arm64 for that workflow. Treat this as a documented SDK prerequisite, not as a universal hardware guarantee for every Harness mode.

3. Rebuild the base runtime

Install the target runtime and the required DeepSeek Harness distribution. Start the official base Web UI or SDK composition before adding custom plugins. The Web UI starts on http://127.0.0.1:3080 by default according to the official user guide.

4. Restore the project only

Clone or copy the project. Check the absolute path, branch, commit, submodules, ignored files, and local changes. Run the read-only repository task. Do not allow edits yet.

5. Restore configuration selectively

Set DSH_HOME deliberately. Copy approved settings and profile layers. Preserve Provider IDs. Compare the target configuration dump with the source record. Recreate environment variable names without copying secret values.

6. Re-inject credentials

Use the target’s controlled credential method. Send a minimal model request in a new session. Confirm the active provider and model. Review runtime output for missing or unexpected credential sources.

7. Rebuild plugins incrementally

Install the base combination. Add plugins one at a time. After each addition, run a read-only task and inspect the configuration tree. Stop at the first failure instead of reinstalling everything.

8. Test session history on a copy

Copy the DeepSeek Harness session logs into a test directory. Confirm that the logs are readable. Attempt limited read-only access first. If the session cannot be safely resumed, create a new session and attach a migration summary.

9. Enable controlled writes

Test one file modification in a disposable branch or checkout. Confirm approval prompts, changed-file scope, and rollback behavior. Then test one approved command. Keep destructive operations disabled until the target passes the earlier checks.

10. Reboot and verify

Stop and restart the cloud process. Confirm that the workspace, model, provider reference, plugin set, permissions, and session directory survive the restart. A migration that works only in one live process is not complete.

[ SECTION_09 ] End-to-end acceptance checklist

[ ] Source revision and runtime versions are recorded.
[ ] Source branch, commit, and uncommitted changes are preserved.
[ ] Target workspace uses the intended absolute path.
[ ] Agent read-only repository analysis matches the source record.
[ ] Target DSH_HOME is explicitly identified.
[ ] Provider IDs match the approved migration record.
[ ] Model selection works in a new session.
[ ] No literal API key appears in the migration archive.
[ ] Runtime logs and terminal history contain no secret residue.
[ ] Base Harness profile starts without custom plugins.
[ ] Plugins are restored from a documented list.
[ ] The first failing plugin or layer can be identified.
[ ] DeepSeek Harness session logs remain available in an untouched backup.
[ ] Copied logs are readable or formally marked as archive-only.
[ ] A controlled file edit succeeds in the intended workspace.
[ ] Command approval behaves as expected.
[ ] The process restarts with the same accepted configuration.
[ ] Source environment retention and rollback conditions are documented.
[ ] Continuous Agent tasks are switched only after acceptance is signed off.

A useful acceptance record includes the test name, source state, target state, expected result, actual result, operator, timestamp, and rollback action. This is more valuable than a screenshot of a working Web UI because it explains what was actually validated.

[ SECTION_10 ] When a cloud Mac is the better migration target

A local Mac is convenient for experimentation, but it becomes a weak long-term target when the machine sleeps, changes networks, is shared with unrelated work, or cannot remain available for continuous tasks. Manual migration also creates repeated configuration drift.

A cloud Mac gives the project a stable remote workspace, a known runtime boundary, and a cleaner separation between personal files and Agent operations. NOVAKVM can be used as a separate rehearsal environment before the source machine is changed. The NOVAKVM Mac environment is the natural starting point for evaluating that workflow, while a Mac rental option for the United States can support a dedicated target for migration testing.

The alternative is still reasonable when the workload is permanent, heavily customized, dependent on physical peripherals, or cheaper to maintain on hardware already owned. Rental is not automatically better for a stable long-running workload. It is most useful when the immediate decision is whether a local DeepSeek Harness setup can be reproduced safely before committing to a permanent environment.

For this migration scenario, the main weaknesses of staying only on the current local setup are clear: it may not remain online, it mixes development and service state, rollback is harder after an in-place upgrade, and another operator cannot easily reproduce the exact environment. A separate cloud Mac reduces those operational risks by giving the migration a clean target, a controlled acceptance window, and a reversible cutover path.

That is why the safer recommendation is to rehearse the move on an independent NOVAKVM Mac first. Keep the source environment untouched, validate the workspace, model, plugins, credentials, and session history, then move continuous Agent tasks only after the target passes the complete checklist.

DeepSeek Harness Migration to a Cloud Mac in 2026