DeepSeek Harness Operator Guide

Service and Updates

Properties2
descriptionImmutable runtime layout, exact Web command contract, controlled promotion, verification, and rollback for deek.service.
tagsdeek, operations, updates

4 min read

Service and Updates

Runtime layout

This layout is a loca deployment decision, not an upstream default.

ItemContract
Unitdeek.service
Application/opt/deek/app, copied from a reviewed source build, owned by root, immutable to the service
Identitysystemd transient deek identity via DynamicUser=yes
State/var/lib/deek via StateDirectory=deek
Harness homeDSH_HOME=/var/lib/deek
Source-loader configTSX_TSCONFIG_PATH=/opt/deek/app/tsconfig.json
Working directory/var/lib/deek/workspace
Writable project tree/var/lib/deek/workspace only
Backend127.0.0.1:52320
Public authoritydeek.loca.zone
Browser openingdisabled with --no-open
Telemetryhard-disabled with DSH_TELEMETRY_DISABLED=1
Operator homehidden with ProtectHome=true

The runtime copy must contain no provider keys, launch tokens, .env values, operator credentials, or writable application code.

Exact Web command contract

The supported upstream source-command semantics are:

pnpm dsh web --host 127.0.0.1 --port 52320 --trusted-host deek.loca.zone --no-open

To preserve /var/lib/deek/workspace as the process working directory, the unit invokes the same upstream CLI entry point through absolute runtime paths:

Environment=TSX_TSCONFIG_PATH=/opt/deek/app/tsconfig.json
ExecStart=/usr/bin/node --import /opt/deek/app/node_modules/tsx/dist/esm/index.mjs /opt/deek/app/apps/cli/src/bin.ts web --host 127.0.0.1 --port 52320 --trusted-host deek.loca.zone --no-open

TSX_TSCONFIG_PATH is load-bearing: the TypeScript source launcher otherwise resolves configuration from the workspace and fails outside the checkout. The unit checks that the entry point, root tsconfig.json, and tsx ESM loader are readable before start.

Operators use systemctl; they do not improvise another loader or run either command manually as loca or root.

Each argument is load-bearing:

  • web selects the shipped Web profile.
  • --host 127.0.0.1 keeps the backend loopback-only.
  • --port 52320 uses the reserved backend port.
  • --trusted-host deek.loca.zone admits the exact public authority to the upstream /api browser-trust fence.
  • --no-open prevents a supervised service from launching a browser.

Do not add 0.0.0.0, a wildcard trusted host, a second public authority, or a different workspace.

Browser bootstrap after start

Upstream generates a browser launch token per process. The service output therefore contains a loopback launch URL, while the remote browser needs the same token exchange on the public origin.

Operator procedure:

  1. Authenticate to https://deek.loca.zone through Authelia.
  2. Obtain the current process launch URL through the restricted operator channel.
  3. Change only its origin to https://deek.loca.zone; preserve the token query exactly and do not expose it elsewhere.
  4. Open it once in the authenticated browser and allow the redirect to remove the query.
  5. Confirm that /api calls use the resulting host-only cookie.
  6. Close any page or tool that still displays the launch URL.

This vault deliberately omits token-extraction and credential-edit commands. Startup output is secret-bearing and must not be copied into shared terminals or logs. A restart rotates the launch token but does not revoke cookies already minted from it because the signing secret persists. If token use is suspected, the deployment owner must use the approved credential-management procedure to rotate or delete the client-connection/browser-session record and then restart, which revokes every browser cookie.

Promote an upstream update

Developer-preview updates may change configuration, state, or frontend compatibility. Use a reviewable, rollback-capable promotion:

  1. Select and review the exact upstream revision in /home/loca/dev/deepseek-harness.

  2. Record the revision and read its release notes, root README.md, and SAFETY.md changes.

  3. Put the operator-local Corepack pnpm shim on PATH as described in the source install guide, then install and build from the source root:

    pnpm install --frozen-lockfile
pnpm run build

  4. Exercise the exact local Web launch on 127.0.0.1:52320 with --no-open in an isolated environment.

  5. Stop deek.service.

  6. Create an access-controlled backup of /var/lib/deek, including the workspace, without printing or exporting credential contents.

  7. Stage a clean runtime copy from the reviewed build. It must be root-owned, immutable to the service, and contain no untracked secrets or operator-home links.

  8. Replace /opt/deek/app atomically through the deployment owner’s release mechanism; never edit the live copy in place.

  9. Start deek.service and verify the unit, loopback listener, Authelia edge, upstream browser authentication, provider availability, and a disposable workspace action.

  10. Record the deployed revision and retain the prior immutable release until the new revision has passed the checks.

The source build and the runtime copy must represent the same revision. A build from one checkout combined with source or node_modules from another is not a valid release.

Roll back

  1. Stop deek.service.
  2. Restore the previous immutable application release.
  3. Restore the matching state backup if the failed revision migrated or rewrote state incompatibly.
  4. Start the service.
  5. Repeat the listener, edge, browser-token, provider, and disposable-workspace checks.
  6. Verify upstream browser authentication; a valid existing cookie survives the process change because its signing secret is persisted.

Do not blindly run an older binary against state already modified by a newer developer-preview revision.

Unit changes

When the unit file itself changes, validate and install it through the deployment owner, then reload systemd before restarting. A routine application update that leaves the unit unchanged does not need a daemon reload.

Graph View

Backlinks