How to Use launchd for DeepSeek Harness Auto-Start in 2026?

The Web UI disappears after a reboot, or the process starts but cannot find Node, npx, the profile, or the API credential.

Fastest fix: use a normal-user LaunchAgent, not a root LaunchDaemon, and verify four separate outcomes: the expected process identity, the listening endpoint, one low-risk Harness task, and recovery after logout, crash, and reboot.

This guide is for:

• Remote Mac users who need DeepSeek Harness to return after a restart or user login.
• Platform engineers who need a consistent process identity, log location, and stop method.
• Delivery owners who must turn “the command starts” into repeatable service acceptance.

Before writing a property list, decide exactly what we are supervising. DeepSeek Harness Web, a Headless one-shot command, and a long-running automation entry point do not have the same lifecycle.

A Web process should normally remain available and listen on a known local address. A Headless task should start, produce an output, and exit with a meaningful status. A scheduled automation process may need its own state directory, lock file, timeout policy, and retry rules.

Do not place all of these behaviors into one LaunchAgent. A job that should exit after producing an artifact may be misdiagnosed as broken if KeepAlive restarts it repeatedly. A Web process may appear healthy while its task runner lacks the correct workspace or credential. The launchd job should supervise one clearly defined responsibility.

The current DeepSeek Harness README documents npm, Python, command-line, MCP, and source-based runtime paths. As of August 19, 2026, it does not confirm a built-in macOS service installer. The service layer in this guide is therefore provided by macOS launchd, not presented as native DeepSeek Harness functionality.

Record these values before deployment:

• The absolute path to the executable or wrapper script.
• The selected DeepSeek Harness profile.
• The absolute working directory.
• The macOS account that owns the process.
• The Web listening address and port, if applicable.
• The stop command or launchctl operation.
• The location of the state directory and generated artifacts.
• The credential source, without copying the secret into the plist.

The path must be absolute. A command that works in an interactive shell because the shell loads a profile, aliases, or a custom PATH may fail under launchd.

For a Web workflow that needs access to a user home directory, profile files, workspace permissions, Keychain access, or a graphical login session, start with a user-level LaunchAgent.

A LaunchAgent in ~/Library/LaunchAgents runs in the selected user’s launchd context after that user logs in. A LaunchDaemon in /Library/LaunchDaemons runs in the system context and is a different security and permission boundary. Apple’s launchd agent and daemon guidance describes user agents as jobs associated with a specific logged-in user, while daemons belong to the broader system context.

This distinction matters for three reasons.

First, a user-level service can normally reach the same home directory, workspace, profile, and session resources that were tested interactively. A root service may instead create root-owned state files, use a different configuration path, or lose access to user-scoped credentials.

Second, using root to avoid a missing path is a poor correction. It changes the process identity without proving that the original environment was complete. If the Web UI contains tools that operate on a workspace, running the whole application as root also increases the impact of a misconfigured tool or plugin.

Third, a root process is not automatically a better remote service. It can make ownership, log rotation, file permissions, and rollback harder to reason about. Use a LaunchDaemon only when the application genuinely requires system-wide startup before login and has been designed for that privilege boundary.

Create the directory and a placeholder plist:

mkdir -p "$HOME/Library/LaunchAgents"
mkdir -p "$HOME/Library/Logs/deepseek-harness"
touch "$HOME/Library/LaunchAgents/com.example.deepseek-harness.plist"
chmod 600 "$HOME/Library/LaunchAgents/com.example.deepseek-harness.plist"

The label above is intentionally a placeholder. Replace com.example.deepseek-harness with a stable label owned by the deployment team. Do not copy the example as a universal finished configuration.

A minimal structure looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>REPLACE_WITH_YOUR_LABEL</string>

    <key>ProgramArguments</key>
    <array>
        <string>/REPLACE/WITH/ABSOLUTE/WRAPPER/PATH</string>
        <string>--profile</string>
        <string>REPLACE_WITH_PROFILE</string>
    </array>

    <key>WorkingDirectory</key>
    <string>/REPLACE/WITH/WORKSPACE/PATH</string>

    <key>StandardOutPath</key>
    <string>/REPLACE/WITH/LOG/DIRECTORY/stdout.log</string>

    <key>StandardErrorPath</key>
    <string>/REPLACE/WITH/LOG/DIRECTORY/stderr.log</string>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <false/>
</dict>
</plist>

The ProgramArguments, working directory, and log paths must be replaced with values from the actual machine. Do not put a real API key in this file. Property lists are configuration files, not a secret-management system.

Apple’s launchd.plist reference documents the role of property-list keys such as ProgramArguments, WorkingDirectory, StandardOutPath, StandardErrorPath, and KeepAlive. The configuration should describe how to start the process, not pretend to understand whether an internal Harness task can resume.

A LaunchAgent does not necessarily receive the same environment as an interactive Terminal session. This is why npx, node, python, a custom profile, or a package manager command can work manually and fail under launchd.

Use discovery commands in the intended account:

command -v node
command -v npx
command -v dsh
pwd
id -un

Then resolve each path:

realpath "$(command -v node)"
realpath "$(command -v npx)"
realpath "$(command -v dsh)"

If command -v npx or command -v node returns nothing inside the LaunchAgent, do not solve the issue by adding a broad system path and hoping for the best. Use one of these controlled approaches:

1. Call the absolute Node path directly.
2. Call a version-managed wrapper script that sets the intended PATH.
3. Install the required runtime in a fixed location owned by the service account.
4. Avoid relying on shell initialization files such as .zprofile or .bashrc.

The launchctl manual explains that launchctl manages services inside launchd domains and that service arguments and environment settings are part of the managed execution context. Treat that context as a separate runtime environment, not as a hidden copy of the Terminal session.

A wrapper script is often easier to audit than a long ProgramArguments array:

#!/bin/zsh
set -u

export PATH="/REPLACE/WITH/NODE/BIN:/usr/bin:/bin:/usr/sbin:/sbin"
export HOME="/REPLACE/WITH/USER/HOME"
export DEEPSEEK_HARNESS_PROFILE="REPLACE_WITH_PROFILE"

cd "/REPLACE/WITH/WORKSPACE" || exit 20

exec "/REPLACE/WITH/ABSOLUTE/NODE" \
  "/REPLACE/WITH/DEEPSEEK/HARNESS/ENTRYPOINT" \
  --profile "$DEEPSEEK_HARNESS_PROFILE"

Set restrictive permissions:

chmod 700 "/REPLACE/WITH/WRAPPER"
chown REPLACE_WITH_USER:REPLACE_WITH_GROUP "/REPLACE/WITH/WRAPPER"

The wrapper should print environment diagnostics only during a controlled test, and it must never echo the API key. Remove temporary diagnostic output before delivery.

The safest choice depends on the runtime’s supported credential mechanism. The key point is that the plist should contain only a reference to the credential source, not the secret itself.

Possible patterns include:

• A protected environment file readable only by the service account.
• A wrapper script that retrieves the value from the macOS Keychain.
• A credential helper supplied by the deployment environment.
• A launchd EnvironmentVariables section containing a reference or non-secret setting, while the secret is injected outside the plist.

Apple’s Keychain Services documentation describes the Keychain as encrypted storage for small secrets and explains that access can be controlled for applications. For a logged-in user LaunchAgent, the Keychain is worth considering when the installed runtime and account policy support non-interactive retrieval.

If the application reads DEEPSEEK_API_KEY, confirm that the LaunchAgent receives it in the same way as the interactive command. A .env file that is found from the project directory may not be found when the working directory is wrong. Conversely, putting the key in a plist makes the secret part of the service configuration and increases exposure during backup, support, or version review.

Use a protected file only if the runtime requires it:

chmod 600 "/REPLACE/WITH/SECRET/FILE"
chown REPLACE_WITH_USER:REPLACE_WITH_GROUP "/REPLACE/WITH/SECRET/FILE"

Then make the wrapper load it without logging its contents:

if [[ -r "/REPLACE/WITH/SECRET/FILE" ]]; then
    source "/REPLACE/WITH/SECRET/FILE"
else
    print -u2 "Credential file is unavailable"
    exit 30
fi

Do not put set -x in this wrapper. Shell tracing can disclose the key through command expansion. Also ensure that Web logs, error logs, crash reports, and task artifacts do not contain authorization headers or full environment dumps.

For stricter access control, review Apple’s guidance on restricting Keychain item accessibility. The exact variable name and profile behavior must still be checked against the DeepSeek Harness release installed on the target Mac. Do not assume that a credential method supported by one release is available in another.

Validate the plist before loading it:

plutil -lint "$HOME/Library/LaunchAgents/REPLACE_WITH_LABEL.plist"

Load it in the logged-in user context:

launchctl bootstrap "gui/$(id -u)" \
  "$HOME/Library/LaunchAgents/REPLACE_WITH_LABEL.plist"

Inspect the job:

launchctl print "gui/$(id -u)/REPLACE_WITH_LABEL"

Then check the process and logs:

pgrep -af "REPLACE_WITH_EXPECTED_PROCESS_PATTERN"
tail -n 100 "$HOME/Library/Logs/deepseek-harness/stdout.log"
tail -n 100 "$HOME/Library/Logs/deepseek-harness/stderr.log"

At this stage, do not begin with repeated crash recovery. First answer four basic questions:

• Is the process owned by the intended account?
• Is it using the expected executable?
• Is its working directory correct?
• Are standard output and standard error being written to maintainable paths?

The LaunchAgent should be inspected in the same user context that is expected to run the Web UI or automation. A job loaded into the wrong domain can appear correctly written on disk while remaining unavailable to the intended session.

If the process exits immediately, inspect the first error rather than increasing KeepAlive. Repeated restarts can hide a bad path, missing environment variable, invalid profile, unavailable workspace, or port conflict. Fix the first failure, unload the job if necessary, and load it again.

For most DeepSeek Harness Web deployments on a remote Mac, the first row is the sensible default. The second row should be an exception justified by a real system-level requirement. The third row is not a production recovery strategy.

If the remote Mac itself is the unstable part of the arrangement, review the available remote Mac options from JEXCLOUD before spending time tuning process supervision. If a regional deployment is required, the Mac rental ordering page can be used after the acceptance requirements are written down.

A process being present does not prove that DeepSeek Harness is usable.

For Web mode, verify the following in order:

1. The process is running under the intended account.
2. The configured address is listening.
3. The Web UI is reachable from the approved remote access path.
4. The selected workspace or profile is correct.
5. A low-risk model task completes.
6. The result is written to the expected location.
7. No secret appears in the browser output or service logs.

Use a local socket check appropriate to the configured port:

lsof -nP -iTCP:REPLACE_WITH_PORT -sTCP:LISTEN

If the Web UI opens but a task cannot run, separate network reachability from application readiness. Common causes include a missing API key, an incorrect profile, a workspace that belongs to another account, a blocked outbound connection, or a tool permission that was available only in the interactive shell.

For Headless mode, the acceptance target is different. Run one deliberately small task and verify:

echo $?
find "/REPLACE/WITH/OUTPUT/DIRECTORY" -type f -mmin -10 -print

A successful process launch with an empty output directory is not a successful Headless deployment. Conversely, an expected nonzero exit code for a deliberately rejected task should not be treated as a service crash. Record the command, expected exit state, artifact path, and error classification.

The difference is important because KeepAlive can restart a process while the underlying task remains failed, duplicated, or incomplete. Process supervision and task durability are separate controls.

Do not sign off the service after one manual launch. Test each recovery event separately and record what actually happens.

User logout and login

Log out the service account, log back in, and inspect:

launchctl print "gui/$(id -u)/REPLACE_WITH_LABEL"
pgrep -af "REPLACE_WITH_EXPECTED_PROCESS_PATTERN"

A LaunchAgent is tied to a user session. If remote access uses a different account, the Web UI may not return in the account that operators expect.

Intentional stop

Stop the job through launchd rather than killing random child processes:

launchctl bootout "gui/$(id -u)/REPLACE_WITH_LABEL"

Confirm that the process and listening socket disappear. Then bootstrap the plist again and verify that only one instance returns.

Abnormal exit

Trigger a controlled failure in a test environment, or terminate the process after recording its PID:

kill -TERM REPLACE_WITH_PID

Observe whether the selected KeepAlive policy produces the desired behavior. Record the recovery point and whether the application opened a new session, resumed an existing task, or simply started a fresh process.

Never describe process restart as task continuation unless the Harness runtime explicitly documents durable task checkpoints and the test proves them.

Full machine restart

Restart the Mac, log in with the service account, and repeat the process, endpoint, credential, and task checks. If the expected behavior is “available after login,” say that clearly. Do not describe it as “available at boot” when the agent requires a user session.

• [ ] The hosted object is documented as Web, Headless, or another single lifecycle.
• [ ] The executable path is absolute and was tested under the service account.
• [ ] The Node, npx, Python, or dsh path does not depend on an interactive shell.
• [ ] The profile name is recorded and resolves from the LaunchAgent environment.
• [ ] The working directory exists and is owned by the intended account.
• [ ] The plist contains no real API key, authorization header, or copied secret.
• [ ] The credential source is readable by the service account and unreadable by unrelated users.
• [ ] Standard output and error logs have known locations and usable permissions.
• [ ] The process identity matches the deployment record.
• [ ] The listening address and port are verified separately from process presence.
• [ ] A low-risk Web task completes without exposing credentials.
• [ ] A Headless task produces the expected artifact and exit state, if applicable.
• [ ] Intentional stop removes the process and does not leave a second instance.
• [ ] Abnormal exit behavior is recorded without claiming task continuation.
• [ ] Logout, login, and full restart tests have been completed.
• [ ] The rollback command and previous executable path are documented.
• [ ] The final acceptance test starts after a clean restart and ends with an end-to-end task.

A service file is part of the release process. When upgrading DeepSeek Harness, stop the old job first, verify that the old process and port are gone, then change the executable or wrapper path. Load the new plist only after the new path works manually under the same account.

Keep the old startup command available until the new version passes the full restart test. Do not change the profile, workspace, state directory, executable, and credential source at the same time unless the release requires it. Changing several lifecycle inputs together makes rollback difficult because a failure can no longer be attributed to one change.

Use separate state directories when testing incompatible candidates. Two processes sharing one state directory may corrupt locks, reuse incompatible session data, or compete for the same port. Keep logs long enough to investigate a failed restart, but remove secrets and rotate files according to the machine’s operational policy.

To disable the service cleanly:

launchctl bootout "gui/$(id -u)/REPLACE_WITH_LABEL"

To enable it again:

launchctl bootstrap "gui/$(id -u)" \
  "$HOME/Library/LaunchAgents/REPLACE_WITH_LABEL.plist"

The launchctl command reference lists bootstrap, bootout, print, and related service-management operations. Use these commands against the intended user domain rather than mixing legacy load and unload commands with a newer deployment process.

If the job must be removed rather than temporarily disabled, archive the plist and logs according to the delivery record before deleting them. The goal is not merely to stop the process. It is to preserve enough evidence to explain which version ran, under which account, with which profile, and why the service was retired.

A normal-user LaunchAgent is usually the lower-cost operational choice for DeepSeek Harness Web on a remote Mac because it avoids unnecessary privilege, keeps ownership aligned with the working files, and makes the login dependency explicit. It is not the right fit for a job that must run before any user session, needs system-wide ownership, or requires physical hardware access that the remote environment cannot provide.

The alternative—an interactive terminal, an improvised root service, or a cloud host with a different filesystem and session model—has real drawbacks: it can lose the process on logout, hide missing environment variables, create root-owned artifacts, expose credentials through copied configuration, or make Web UI and workspace behavior diverge from local tests. If the current Mac cannot provide a stable continuous usage window, a managed remote Mac from JEXCLOUD is easier to evaluate when the deployment is tied to a documented account, fixed paths, and a restart acceptance record.

Before delivery, save a sanitized copy of the checklist and test results. The service is ready only when a clean restart ends with the intended process, reachable Web UI where applicable, valid credential access, and one completed low-risk task—not merely when launchctl reports that a job was loaded.

• Troubleshoot Web UI startup, remote access, workspace, and approval failures
• Keep a remote Mac service persistent with LaunchAgent, SSH tunneling, and health checks
• Handle launchd restart loops, version drift, health checks, and safe upgrade rollback