Run dsh --profile web and the interface opens in your default browser, ready for interactive chat with the agent. You get the conversation view, model and settings management, and session history, backed by the same model access, tools, and safety defaults as every other surface. The command prints a tokenized startup URL; the browser exchanges that token for a signed session cookie and redirects to the clean root URL. You can change the port, suppress the browser handoff, and allow extra hosts from the command line; binding all network interfaces is intentionally not supported. Choose it for interactive work in the browser; dsh-headless is the one-shot command-line sibling.

Use this package
Understand the implementation
Further Exploration
Model Experience
Known Limitations and Deferred Work
Dev Note

Use this package

Start the GUI, open your browser, and start talking to the agent. The flags fine-tune the invocation.

Starting the Web GUI

dsh --profile web
dsh --profile web --no-open --port 8080

After startup you see a dsh web: line whose root URL carries a fresh process token. Unless --no-open or an SSH session suppresses it, the default browser opens that URL, receives a signed cookie, and redirects to the clean root page. You know it worked when the page loads and you can chat with the agent. Two failures to expect: if the frontend is not built, startup stops with a build hint (pnpm run build in a checkout); if the browser cannot be opened, a credential-free diagnostic prints to stderr while the server keeps running — open the printed startup URL yourself.

Configuration

Most users never set these; the command-line flags feed the four settings below — --host, --port, and --trusted-host come from the invocation, and --no-open turns the browser handoff off for that invocation:

Field	Default	Meaning
`openBrowser`	`true`	Open the default browser after startup; SSH launches suppress it
`printUrl`	`true`	Print the `dsh web:` URL line at startup
`surfaceContext`	`true`	Give the agent GUI-orientation context and expose `DSH_WEB_URL` to its shell commands
`trustedHosts`	`[]`	Extra hosts allowed to reach the GUI from the network

The generated configuration catalog is the exhaustive source for every accepted field and its JSDoc.

LAN access and trusted hosts

By default the GUI accepts connections from this machine only. A deployment that binds all network interfaces also allows browsers from the LAN, and the printed URL then includes a LAN address; --trusted-host adds extra hosts in either case. Host and Origin checks control reachability, while the token exchange authenticates every Host API method and WebSocket stream. The LAN addresses are sampled once at startup, so a network change later is not picked up — restart the GUI to re-advertise.

Running over SSH

When you launch dsh --profile web over SSH, the URL line still prints but the browser is not opened for you: the SSH client or editor owns the local forwarding address. Open the forwarded URL on your machine yourself; the printed URL names the remote host's loopback endpoint.

Per-session agent setup

Each browser session composes its own agent from the shipped presets (the standard preset by default), instead of sharing one process-wide tool set. You can change the default preset or add your own presets under $DSH_HOME/.agent-presets.

Understand the implementation

Implementation internals — click to expand

The bundle is one patch plus one runtime glue plugin. The storage stack and projection cache come from dsh-base; the web overlay's workspace and message-feedback rows consume that shared storageDomain service. The patch restates the surface-specific values the base deliberately omits, inserts the web-only host rows and browser roster, then moves the agent plane behind presets. The glue plugin owns dist serving, trust sampling, prompt sections, the bash variable, and the readiness announcements.

Patch semantics

A patch replaces the targeted row's whole config, so each web row restates every key it owns: the persona, the DSH_TOOLS_MODE PTC mode opt-in, and the session-query-sqlite values on the base rows, then insert adds the web host rows, transport, and browser roster. The per-agent tool rows the base mounts process-wide are disabled here and the preset roster takes over; the reasoning for each host-plane versus preset-plane decision is inline in the patch.

Readiness

The URL line and browser handoff are readiness signals: supervisors RPC as soon as they observe the line, and a browser requests the page as soon as it opens, so both run only after the Loader tree settles and Connection authentication is available — or immediately in a hand-built tree without a Loader. A tree disposed mid-boot announces nothing.

LAN trust sampling

resolveLanTrust samples the network once at boot: a loopback bind (127.0.0.1) derives no LAN addresses, while an all-interfaces bind adds every non-internal IPv4 literal. The derived literals plus the explicit --trusted-host authorities form the /api browser-trust fence, and the printed LAN URL always matches that fence.

Source map

File	Role
`src/index.ts`	The `web-app` glue plugin: dist resolution, LAN trust sampling, prompt sections, bash variable, URL line, browser handoff
`src/startup.ts`	The `web-startup` provider: `--host`, `--port`, `--trusted-host`, `--no-open`, `--help`
`cordis.patch.yml`	The web patch: restated base values, web host rows, browser roster, agent plane behind presets
`src/invariant.ts`	Invariant companion: no runtime invariant; every contribution is registry-disposed
`tests/web-app.spec.ts`	Dist resolution, fallback seat, prompt sections, readiness
`tests/startup.spec.ts`	Command-line parsing over a real Loader tree
`tests/trusted-hosts.spec.ts`	LAN-trust sampling
`tests/browser-open.spec.ts`	Default-browser handoff after the page is reachable

Invariant ownership

The invariant companion registers an empty installer because every contribution — the frontend-static child plugin, the prompt sections, and the bash variable registration — is registry-disposed with the fiber, and each owning registry's package carries that relation's invariant.

Further Exploration

Read these pages when you want to go deeper into the shared core, the browser reload pipeline, or the built frontend.

Bundle package map — the surfaces built on the same core.
dsh-base — the shared core the GUI runs on.
dsh-client-hmr — how client-plugin changes reload during development.
frontend-static — how the built frontend is served.
Generated configuration catalog — every accepted config field and its source declaration.

Model Experience

Harness-source and Web-surface context

What the model sees

When surfaceContext is true, the harness:source section identifies the on-disk Harness implementation without claiming it is the working directory, and the app:web-surface global section (first-party order −800) orients the model to the GUI: the canonical local URL, the "this page" referent, the update contract (the reload receiver is always on; no-refresh reloads additionally need the pnpm run dev:web watcher), and the instruction not to start replacement servers. DSH_WEB_URL additionally appears in the managed bash environment with its description, resolved per invocation from the live server. When it is false, neither section nor the variable is registered.

Token effect

One source line and one prompt paragraph per session plus two managed-environment variable lines; constant per process.

KV Cache effect

The prompt section sits near the system prompt's head and is stable for the life of the process (the port is a boot fact), so it does not invalidate the cache across turns.

Known Limitations and Deferred Work

These limits tell you what to expect in unusual setups — a source checkout, SSH sessions, or strict networks. They are current package constraints, not a general browser comparison or a task backlog.

The frontend must be built — a source checkout needs pnpm run build first; startup stops with a build hint when the dist is missing, and there is no source-serving fallback.
LAN addresses are sampled once at startup — interface changes after boot are not re-advertised; the printed LAN URL always matches what was sampled.
Only the handoff start is observable — the GUI reports that the browser was asked to open, not that it actually opened; a later browser exit is never reported, and the printed URL is your manual fallback.
SSH sessions keep the URL but skip the browser handoff — the printed URL names the remote host's loopback endpoint; the SSH client or editor must expose and open the local forwarded address.
BROWSER overrides only come from the environment — a discovered .env cannot set BROWSER; only an inherited value can choose the executable for the automatic handoff.
Binding all network interfaces is not supported — --host 0.0.0.0 is rejected at startup for safety; use the default loopback host.

Dev Note

Working context for maintainers — click to expand

None.

README.md Unescape Escape

@deepseek-ai/dsh-web-app

Summary

Table of Contents