DeepSeek Harness Operator Guide

First Provider and Session

Properties2
descriptionComplete both browser gates, store a provider key without exposing it, select the isolated workspace, and use Web or CLI modes.
tagsdeek, quickstart, providers

4 min read

First Provider and Session

Authenticate the public browser

The public deployment has two independent authentication steps:

  1. Authelia applies one_factor before nginx proxies the browser surface.
  2. DeepSeek Harness exchanges its per-process launch token for a browser session cookie.

Upstream binds the cookie to the normalized browser hostname and port. It is host-only, HttpOnly, and SameSite=Strict. The launch token is accepted only on GET /; the server then redirects to / without the token. Every /api request must present the cookie and an accepted Host authority.

For deek.service, complete the exchange at the public origin https://deek.loca.zone, not at the loopback URL printed by the process. The service admits that authority through:

--trusted-host deek.loca.zone

Launch token handling

The launch URL is a process credential. Use the operator-approved private bootstrap path, never publish it, and never save it in this vault. A service restart rotates the launch token, but the persisted cookie-signing secret means existing valid cookies survive and no fresh exchange is normally required. Suspected token use requires approved rotation or deletion of the client-connection/browser-session credential plus restart to revoke all cookies.

Authelia is the outer identity gate; it does not replace the upstream cookie. The upstream cookie proves possession of the process token; it does not identify the person. Keep both layers.

Configure DeepSeek without exposing the key

  1. Open Settings → Models in the authenticated Web UI.
  2. Enter the DeepSeek API key in the DeepSeek card.
  3. Save the card.
  4. Select a configured model from the model picker.

Upstream behavior:

  • The key field is write-only.
  • After saving, the page receives a redacted descriptor, never the literal key.
  • The credential is stored in $DSH_HOME/.credentials.yaml.
  • $DSH_HOME/settings.yaml retains only the credential reference and provider settings.
  • Provider and model changes apply on the next request without restarting the server.
  • Selecting a model makes it the default for new sessions; an existing session that has sent a request keeps the model recorded in its log.

Loca policy:

  • Use the gated Models page for the first key.
  • Do not put provider values in Git, Markdown, unit files, command arguments, shell history, or shared logs.
  • Do not copy the credentials file out of /var/lib/deek except into an access-controlled backup.

Select the isolated workspace

A fresh Web UI has no selected workspace.

  1. Select Choose workspace.
  2. Add /var/lib/deek/workspace.
  3. Select that directory.
  4. Create a new session.

The invoking directory is upstream’s default filesystem location, but the loca unit pins it to the dedicated workspace. Do not add /opt/deek/app, /var/lib/deek, /home, the operator checkout, or any credential directory to the picker.

New base-backed sessions default upstream to workspace-write. Mutations are restricted to the selected workspace and platform temporary roots, but reads and network access are not confined. Treat every file and network destination visible to the process as reachable.

Run a Web task

A session can read and edit workspace files, execute commands, delegate, and maintain a plan. Approval prompts appear when the active permission policy requires them.

Start with a bounded task against disposable content, inspect every proposed action, and verify the resulting files before increasing scope. Stored General permission changes affect later Web sessions, not a session that is already open.

Use CLI modes from source

The Node application has one supported launcher: dsh. From the repository root, use the pnpm wrapper:

pnpm dsh web --host 127.0.0.1 --port 52320 --no-open
pnpm dsh --profile headless "Summarize this repository"
pnpm dsh --profile acp
pnpm dsh --profile sdk
pnpm dsh --profile sdk-minimal
ModeBehavior
webBrowser application. The exact local launch remains loopback-only on port 52320 with --no-open.
headlessRuns one fresh persisted session, prints the final answer, and exits.
acpServes an ACP automation client over stdio until disconnect.
sdkServes SDK clients over JSON-RPC stdio.
sdk-minimalServes the smaller standalone SDK tree over JSON-RPC stdio.

The stdio and one-shot modes do not accept Web host, port, or browser flags. They are not exposed by deek.service and must run only in an appropriately isolated local environment.

Next references

Graph View

Backlinks