DSH public access: public-url, trusted-host and TLS

Publishing DeepSeek Harness takes three settings that work together: --public-url announces the external address, --trusted-host admits the browser authority, and TLS protects the cookie. They are not interchangeable. With only public-url, every API returns 403. With only trusted-host, printed URLs are wrong. With only TLS, a subpath deployment still breaks on cookies.

DeepSeek Harness: What --public-url announces

--public-url changes presentation, not the routes the listener serves. The official scope:(source)

It accepts an http:// or https:// root, optionally with a mount prefix, and normalizes it to a trailing slash. The listener still serves origin-root routes and never learns about /ui. In other words: public-url says “where I am”, not “move the listener there”.

The most common mistake is treating --public-url as authorization. The official docs are clear: the announced URL and the trust fence are separate.

DeepSeek Harness: What --trusted-host admits

If the browser authority is not on the fence list, every /api call returns 403 even when the proxy is perfect. The fence accepts three sources:(source)

1. Loopback — direct access through 127.0.0.1 or localhost.
2. The listener’s binding address — whatever address the listener binds.
3. --trusted-host entries — repeatable; an entry without a port matches any port, which suits tunnels that bind different ports.

Configuration:

dsh web \
  --public-url https://app.example/ui/ \
  --trusted-host app.example

1. Read the browser authority — app.example or app.example:8443. Expected: the value matches exactly.
2. Omit the port when it changes — a hostname-only entry matches any port. Expected: tunnels keep working after a port change.
3. Restart and re-check — open the tokenized URL and inspect an /api request. Expected: no 403; if it persists, check whether the proxy rewrites Host.

The fence only admits requests. Authentication still comes from the startup token and the signed session cookie. TLS termination does not change that.

DeepSeek Harness: Five jobs for the reverse proxy

A proxy is not just “forward the request”; the official contract has five hard requirements. Check each:(source)

1. Preserve the browser-visible Host — the fence compares it with the authority. Expected: the backend sees the external hostname.
2. Strip the mount prefix — /ui/api/... must arrive as /api/.... Expected: no prefix reaches the listener.
3. Forward upgrades — every request and WebSocket upgrade must carry Upgrade and Connection. Expected: real-time output keeps refreshing.
4. Rewrite cookie scope — the backend issues a host-only Path=/ cookie; the proxy changes Path to /ui/ and adds Secure only on HTTPS. Expected: the browser returns the cookie only on that subpath.
5. Redirect the bare mount — /ui must arrive as /ui/; only /ui/ exchanges the startup token, while /ui/index.html works once a cookie exists. Expected: no 404 on the bare mount.

Items 1 and 4 fail most often. The first produces 403; the second produces a login loop.

DeepSeek Harness: Three details that bite after “the page opens”

These are not TLS handshake problems, and each has a distinct symptom. Check them separately:(source)

1. Host must stay intact — rewriting it to the listener address removes the external domain from the fence. Expected: the backend sees the browser authority.
2. /ui must become /ui/ — only the slash form exchanges the token; a cookie holder can also load /ui/index.html. Expected: the bare mount does not 404.
3. Cookie Path and Secure are separate — change Path to the mount and add Secure only on the HTTPS hop. Expected: no cookie leak over HTTP.

One more boundary: neither the announced URL nor the fence protects the listening port. Restrict the port to a trusted proxy or internal network; do not expose it just because TLS is on.

DeepSeek Harness: Three TLS and cookie combinations

TLS can terminate at the proxy, at the listener, or at both; the difference is who adds Secure and who rewrites Path. Compare:(source)

Native TLS uses --tls-cert and --tls-key; the certificate needs a full chain and the key must be unencrypted. Files are read once at startup, so rotation requires a restart or reload.

The browser-facing link should always be HTTPS. An http:// root exposes the startup token in clear text, and that token is a process credential.

DeepSeek Harness: Pre-flight checklist

Separate “the page opens” from “the app works”, or you will misread 403 as a TLS failure. Run in order:(source)

1. Local listener — curl -vk https://127.0.0.1:3080/. Expected: TLS handshake succeeds.
2. Proxy forward — curl -v https://app.example/ui/. Expected: the page returns, no 502.
3. Response headers — inspect Set-Cookie for Path and Secure. Expected: Path=/ui/, Secure on HTTPS.
4. API call — pick one /api request in devtools. Expected: 200, not 403.
5. WebSocket — watch real-time output. Expected: the connection stays open.

If 1 and 2 pass but 4 returns 403, check --trusted-host and Host rewriting. If 3 is wrong, fix the proxy’s Path/Secure rewrite.

DeepSeek Harness FAQ

Can --public-url omit the scheme? No. The official flag expects an http:// or https:// root; without a scheme it cannot normalize or generate external URLs.

Can I use an IP address? Yes, but --trusted-host must contain the exact IP authority and the certificate must cover that IP, or name validation fails.

Does the fence protect the listening port? No. The official docs say neither the announced URL nor the fence protects the port itself. Keep the port behind a trusted proxy or internal network.

The short version: public access is not “add a proxy”; it is announced address, trust list, TLS, and cookie path aligned. 403 points at the authority; a login loop points at cookie Path.