token-weather · Claude Code mod

Preview · a replayed session in a sandbox

claude · ~/work/app · token-weather

› fix the failing auth test and add an audit log call ⏺ Read(src/auth.ts) ⎿ Read 6 lines ⏺ Update(src/auth.ts) ⎿ Added 2 lines, removed 1 line ⏺ Bash(bun test) ⎿ 3 pass, 1 fail ● Done. refresh now rejects expired claims and logs an audit event. ✻ Worked for 42s · done 4:20 PM ☁ Cloudy 49% of context 97.4k / 200k last turns ██ steady ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── › ? for shortcuts

Draws

Band

☁ Cloudy 49% of context 97.4k / 200k last turns ██ steady

README

DeepSeek Harness — Community Fork

English | 中文

Español

A self-service distribution of DeepSeek Harness (dsh) for home servers and LAN deployments. It adds a one-command Docker setup, local-network and reverse-proxy access, and declarative environment configuration — without rewriting upstream code, so git merge upstream/master stays cheap.

Safety notice: DeepSeek Harness executes model-generated code. Read SAFETY.md before exposing it to your network, and only trust hosts you control.

What this fork changes

Upstream binds to 127.0.0.1 only and rejects LAN or proxy access by design. This fork keeps upstream's security model but makes it declarative:

LAN access (http://<your-ip>:3080) through an explicit trusted-hosts allowlist (DSH_TRUSTED_HOSTS) instead of hard-coded 403 rejections.
Reverse-proxy support (Nginx, Caddy, Traefik, Cloudflare Tunnel): forward X-Forwarded-Host / X-Forwarded-Proto and the trust fence and session cookies follow the browser-facing authority.
Settings UI unlocked for clients on trusted hosts — not just localhost.
Built-in Dynamic Port Proxy (/proxy/<port>/): view and interact with web servers, frontends, and preview apps started by the agent on any internal port (e.g. http://<server-ip>:3080/proxy/8210/, 5173, 3000) through the single DSH port without opening extra Docker ports.
Headless Browser & Visual Inspection: the Docker image includes Chromium, system graphics libraries, and pre-installed Playwright so agents can run headless browsers, take WebGL screenshots, and visually self-verify out of the box.
Docker-native plugin management: pnpm is preinstalled and its store persists on the /data volume.
Structured diagnostics: rejected requests log an exact, credential-free reason (untrusted host "…", origin mismatch (…), session cookie expired at …) to docker compose logs.
Telemetry denied by default: the OTel session telemetry, the Desktop product analytics, and the non-inference metadata carried on official DeepSeek API requests (dsh_session_log, dsh_plugin_packages) all ship off, and no collector URL is baked in. Each has an explicit opt-in, and DSH_TELEMETRY_DISABLED overrides all of them. See Telemetry and privacy.
Spanish interface: the Web UI ships English, Chinese, and Spanish. It follows your browser language, and Settings pins an explicit choice.

Everything else — the agent loop, plugins, session storage — is upstream code, unmodified.

Run

Run with Docker

See Quick start (Docker) above.

Run from source

See Running from source (no Docker) below.

Quick start (Docker)

Requirements: Docker Engine 24+ and Docker Compose v2.

git clone https://github.com/samuelrubiodev/deepseek-harness-community.git
cd deepseek-harness-community
cp .env.example .env
docker compose up -d --build

Open http://<server-ip>:3080 and paste your DEEPSEEK_API_KEY in the onboarding dialog (or set it in .env first). The first build compiles the TypeScript monorepo and takes a few minutes; later starts are immediate.

Prefer not to build? The fork publishes multi-arch (amd64/arm64) images to GitHub Container Registry (GHCR) at ghcr.io/samuelrubiodev/deepseek-harness-community with tags :stable (latest tagged release), :latest (latest build from default branch master), and :dsh-v<version> (pinned release versions, e.g. dsh-v0.1.7-alpha.2-community.1); the templates in deploy/nas/ pull from it with no login, no checkout, and no build — designed for NAS hosts (Synology, Unraid, TrueNAS) and servers.

Two volumes persist all state across upgrades and container recreation:

Volume	Mount	Contents
`dsh-data`	`/data`	`$DSH_HOME`: sessions, profiles, plugins, credentials, settings
`dsh-workspace`	`/workspace`	The directory the agent works in and your projects

Check health and logs (expect Up (healthy)):

docker compose ps
docker compose logs -f harness

Running on a NAS (Synology, Unraid, TrueNAS) or a server without a build toolchain? Use the templates in deploy/nas/ and load a prebuilt image. Day-2 operations — backup of /data, restore, update pinning, and rollback — are scripted in deploy/operations/.

Configuration

All knobs are environment variables, documented exhaustively in .env.example. Copy it to .env and restart with docker compose up -d.

Variable	Default	Purpose
`DSH_HOST`	`0.0.0.0`	Interface the server binds to inside the container.
`DSH_PORT`	`3080`	Listening port (also mapped by Compose).
`DSH_TRUSTED_HOSTS`	(empty)	Comma-separated hostnames/IPs allowed to reach the Web UI, e.g. `192.168.1.50,harness.lan`. Requests with any other `Host` header get 403.
`DSH_REVERSE_PROXY`	`false`	Set `true` behind Nginx/Caddy/Traefik/tunnels: the proxy's `X-Forwarded-Host` / `X-Forwarded-Proto` then drive trust and cookie authority.
`DSH_AUTH_MODE`	`token`	`token`: sign-in requires `/?token=…`. `none`: no token or cookie — only `DSH_TRUSTED_HOSTS` gates access (see below).
`DSH_AUTH_TOKEN`	(empty)	Fixed sign-in token replacing the random per-start launch token, so your URL survives restarts.
`DEEPSEEK_API_KEY`	(empty)	DeepSeek API key; can also be entered in the Web UI.
`DSH_HOME`	`/data`	Durable state root inside the container.

DSH_* variables are process-level bootstrap configuration: Compose injects them natively, and the layered env loader rejects them inside project .env files — put them in the repository root .env (or the Compose environment: block), never in /workspace/.env.

LAN access

Add every address users type into the browser to DSH_TRUSTED_HOSTS, then restart:

DSH_TRUSTED_HOSTS=192.168.1.50,harness.lan docker compose up -d

Hosts on that list also get the persistent Settings panel in the Web UI.

Sign-in token

By default each start mints a random launch token and announces http://<host>:<port>/?token=… — read it from the logs every time you restart. Two ways to stop hunting for it:

# 1. Stable URL: set your own token once; the sign-in link never changes again.
DSH_AUTH_TOKEN=my-long-random-secret docker compose up -d
# open http://192.168.1.50:3080/?token=my-long-random-secret

# 2. No token at all: any host on the trust fence reaches the UI directly.
DSH_AUTH_MODE=none docker compose up -d

With DSH_AUTH_MODE=none the Web UI — including the agent's code-execution tools — is reachable by every machine whose address passes DSH_TRUSTED_HOSTS. Use it only on networks you fully control; the Host/Origin trust fence (section above) remains active either way, and this fork's Docker image logs a warning at startup when the mode is off.

Reverse proxy

Reference configurations with TLS termination, WebSocket passthrough (/api/remote.mux), streaming-friendly buffering off, and long timeouts live in deploy/reverse-proxy/ for Nginx, Caddy, Traefik, and Cloudflare Tunnel. Minimum contract for any proxy:

Set DSH_REVERSE_PROXY=true and add the public hostname to DSH_TRUSTED_HOSTS.
Forward X-Forwarded-Host: $host and X-Forwarded-Proto: https (at TLS-terminating proxies).
Pass Upgrade / Connection headers and disable response buffering.

Telemetry and privacy

Nothing leaves your deployment unless you opt in. Every telemetry channel and every non-inference contribution to official DeepSeek API requests is denied by default, and no collector URL is baked in.

Variable	Default	Purpose
`DSH_TELEMETRY_ENABLED`	(empty)	Opt in to the OpenTelemetry channels. Session telemetry additionally needs `DSH_TELEMETRY_MODE=FEEDBACK_ONLY` and `DSH_TELEMETRY_OTLP_URL`; Desktop product analytics additionally needs `DSH_PRODUCT_ANALYTICS_OTLP_URL`.
`DSH_TELEMETRY_MODE`	`DISABLED`	Session telemetry sharing policy. `FEEDBACK_ONLY` releases the canonical session prefix only after new explicit feedback; `FULL` is rejected.
`DSH_TELEMETRY_OTLP_URL`	(empty)	OTLP logs endpoint for session telemetry. An uploading mode requires it, and an opted-in process without it fails at load.
`DSH_PRODUCT_ANALYTICS_OTLP_URL`	(empty)	OTLP logs endpoint for Desktop product analytics.
`DSH_SESSION_LOG_UPLOAD`	(empty)	Opt in to attaching the canonical session log to official DeepSeek API requests.
`DSH_PLUGIN_INVENTORY_UPLOAD`	(empty)	Opt in to attaching the installed plugin inventory to official DeepSeek API requests.
`DSH_TELEMETRY_DISABLED`	(empty)	Overrides every opt-in above. Any non-empty value denies, including `0` and `false`.

The DeepSeek inference path is unaffected: api.deepseek.com requests, the harness identity request headers, and user-agent behave the same whether or not telemetry is enabled.

Upgrading

./scripts/sync-upstream.sh --check
./scripts/sync-upstream.sh --merge

The sync tool and its conflict-resolution runbook are documented in deploy/sync/README.md. Before merging, pin a rollback point and back up your data; the merge itself never touches /data:

./deploy/operations/update-image.sh save
./deploy/operations/backup-data.sh --service

Recreate after building (docker compose up -d --build), and if the new image misbehaves, move the tag back with ./deploy/operations/update-image.sh rollback. Full update, backup, restore, and rollback procedures — plus NAS deployment templates — are in deploy/operations/README.md.

Running from source (no Docker)

Same requirements as upstream: Node.js ^22.19 or 24 and pnpm 11.

pnpm install
pnpm run build
DSH_HOST=0.0.0.0 DSH_TRUSTED_HOSTS=192.168.1.50 pnpm dsh web --no-open

--host 0.0.0.0 prints a safety warning and binds all interfaces; combine it with DSH_TRUSTED_HOSTS to decide who may connect.

Troubleshooting

Read the rejection reason from the logs first — every 403/401 names its exact cause:

Log message	Cause	Fix
`untrusted host "…"`, `trustedHosts: (…)`	`Host` header not on the allowlist	Add the host to `DSH_TRUSTED_HOSTS` and restart
`origin mismatch ("https://…" vs "http://…")`	TLS terminated at the proxy but `X-Forwarded-Proto` not forwarded	Set `proxy_set_header X-Forwarded-Proto https;`
`session cookie authority mismatch`	Cookie minted for a different host/port	Reopen the startup URL through the same proxy authority
`session cookie expired at …`	30-day cookie lifetime elapsed	Reopen the URL printed by `dsh web` to re-authenticate

Healthcheck: the container probes http://127.0.0.1:<port>/ and treats 200/303/401 as healthy — a 401 is the expected unauthenticated challenge, proving the HTTP server and Cordis runtime are alive.

Repository layout (fork-specific)

docker/                    Dockerfile, entrypoint, healthcheck, Cordis bind patch
docker-compose.yml         Production-ready orchestrator (uses .env)
.env.example               Exhaustive declarative configuration template
deploy/reverse-proxy/      Reference Nginx / Caddy / Traefik / Tunnel configs
deploy/nas/                Synology / Unraid / TrueNAS / server Compose templates
deploy/operations/         Backup, restore, update and rollback scripts and guide
deploy/sync/               Upstream sync runbook
scripts/sync-upstream.sh   Automated upstream merge with conflict simulation
.github/workflows/docker-publish.yml  Multi-arch image publishing to GHCR
deploy/lab/                Reproducible test lab (proxy scenarios, WebSockets, SSL)

Upstream packages/, apps/, and documentation are unmodified except for the trusted-hosts, reverse-proxy, and diagnostics features described above.

Community and support

Submit feedback or bug reports through GitHub Discussions. Fork-specific issues go to this repository's issues.
Add the dsh-plugin topic to your plugin repository for discoverability.
Join <a href="https://discord.gg/4MrtZUhpxg">DeepSeek Harness Discord community</a>.

Contributing

See CONTRIBUTING.md.

Development

Start with the development guide and architecture documentation.

pnpm run dev:web builds, serves, and rebuilds client bundles on source edits in one terminal, and make help lists the matching Make targets for Web and Desktop; the guide's application commands section owns the full table.

For agents, follow AGENTS.md.

Citation

@misc{deepseek-harness2026,
  title={DeepSeek Harness: Everything is a Plugin},
  author={DeepSeek-AI},
  year={2026},
  publisher={GitHub},
  howpublished={\url{https://github.com/deepseek-ai/deepseek-harness}},
}

License

MIT, matching upstream. Third-party notices: THIRD_PARTY_NOTICES.md.

Source 2 files

hooks/token-weather.mjs 88 lines

1// Token Weather, from "Getting started with Claude Code mods"
2// (https://claude.dev/blog/getting-started-with-claude-code-mods/, Anthropic, 2026-10-01).
3// The published module, unchanged.
4
5// Token Weather: a live forecast of the context window, above the prompt.
6
7const HISTORY = 12;
8const BARS = "▁▂▃▄▅▆▇█";
9const FORECAST = [
10  { upTo: 25, icon: "☀", word: "Clear", color: "yellow" },
11  { upTo: 50, icon: "☁", word: "Cloudy", color: "cyan" },
12  { upTo: 75, icon: "☂", word: "Showers", color: "blue" },
13  { upTo: 90, icon: "☇", word: "Storm", color: "magenta" },
14  { upTo: Infinity, icon: "↯", word: "Compact soon", color: "red" },
15];
16
17// Held by the host, so the history survives a hot reload of this file.
18const readings = { plugin: "token-weather", key: "readings" };
19
20export function register(on) {
21  on("session.start", async ($, e, next) => {
22    const result = await next(e);
23    await takeReading($);
24    return result;
25  });
26
27  on("turn.complete", async ($, e, next) => {
28    const result = await next(e);
29    if (!e.agentId) {
30      await takeReading($); // main-loop turns only, not subagents
31    }
32    return result;
33  });
34
35  on("ui.render", { component: "AbovePrompt" }, async ($, e, next) => {
36    const { value: history = [] } = await $.state.get(readings);
37    if (e.props.hasSurvey || history.length === 0) {
38      return next(e);
39    }
40    const { Box, Text } = $.ui.resolve(e);
41    return band(Box, Text, history, e.props.bodyColumns);
42  });
43}
44
45async function takeReading($) {
46  const { context } = await $.session.usage();
47  if (!context?.window) return;
48  const tokens = context.tokens ?? 0;
49  const percent = context.percent ?? Math.round((tokens / context.window) * 100);
50  const { value: history = [] } = await $.state.get(readings);
51  await $.state.set(readings, [...history, { tokens, window: context.window, percent }].slice(-HISTORY));
52}
53
54function band(Box, Text, history, columns) {
55  const now = history[history.length - 1];
56  const f = FORECAST.find((b) => now.percent < b.upTo);
57  const parts = [
58    Text({ color: f.color, bold: true, children: `${f.icon}  ${f.word}` }),
59    Text({ children: `  ${now.percent}% of context` }),
60    Text({ dimColor: true, children: `  ${short(now.tokens)} / ${short(now.window)}` }),
61  ];
62  if (columns >= 60) {
63    parts.push(Text({ dimColor: true, children: "   last turns " }));
64    parts.push(Text({ color: f.color, children: sparkline(history) }));
65    if (history.length > 1) {
66      parts.push(Text({ dimColor: true, children: trend(history) }));
67    }
68  }
69  return Box({ flexDirection: "row", paddingX: 1, children: parts });
70}
71
72function sparkline(history) {
73  const top = Math.max(...history.map((r) => r.tokens), 1);
74  return history.map((r) => BARS[Math.floor((r.tokens / top) * (BARS.length - 1))]).join("");
75}
76
77function trend(history) {
78  const delta = history[history.length - 1].tokens - history[history.length - 2].tokens;
79  if (delta === 0) return "  steady";
80  return delta > 0 ? `  ▲ +${short(delta)} last turn` : `  ▼ ${short(-delta)} last turn`;
81}
82
83function short(n) {
84  if (n >= 1_000_000) return `${+(n / 1_000_000).toFixed(1)}M`;
85  if (n >= 1_000) return `${+(n / 1_000).toFixed(1)}k`;
86  return String(n);
87}
88

types/index.d.ts 11 lines

1// Token Weather's type contract, from https://claude.dev/blog/getting-started-with-claude-code-mods/
2// (Anthropic, 2026-10-01). The published file, unchanged.
3
4export type TokenWeatherReading = { tokens: number; window: number; percent: number }
5
6declare module 'claude-code' {
7  interface PluginState {
8    'token-weather': { readings: TokenWeatherReading[] }
9  }
10}
11