SandBaseSandBase
Start building

Getting Started · 02

Launch the DeepSeek Harness Web UI in Five Minutes

Start the browser interface in a disposable workspace, configure a model safely, run an observable first task, and diagnose failures by layer.

Reading time
14 minutes
Sources verified

Define what a successful first run must prove

A useful quickstart should prove more than ‘the page opened.’ Your first run needs to establish five independent facts: the launcher can boot the shipped Web profile; the browser passes the host trust boundary; the runtime can resolve a model credential without exposing it back to the page; a selected workspace becomes the session's filesystem root; and a session can execute a bounded task whose evidence survives reload. Keeping these facts separate makes troubleshooting faster because each failure belongs to a different subsystem.

Use a disposable checkout or a newly created directory. The Web agent can read and edit workspace files, run commands, delegate work, and maintain a plan under the active permission policy. A directory that contains production configuration, private repositories, or broad credentials is therefore a poor quickstart target. The objective is to observe a minimal, reversible interaction before you authorize writes or connect a company gateway.

  • Success: the server prints a loopback URL and the browser loads it.
  • Success: a provider appears in the model picker after its credential is saved.
  • Success: selecting a workspace enables the composer.
  • Success: a read-only prompt reports facts that match files in that workspace.
  • Success: refreshing the browser preserves the session transcript and tool evidence.

Prepare Node.js, the launcher, and an isolated workspace

The published npx path is the fastest entry point. npx requires a working Node.js installation and network access to the npm registry when the package is not already cached. The source repository itself currently supports Node.js 22.19+ and 24+ and pins pnpm 11.7.0 for contributors, but the quickstart does not require cloning or building the monorepo. If you later switch to source execution, use those repository-owned floors rather than assuming that any local Node and pnpm pair is supported.

Create the workspace before launching. The invoking directory becomes the default filesystem location for every profile. A fresh Web UI still has no selected workspace until you add one in the browser, but starting from the intended directory makes the path obvious and avoids accidentally offering a parent folder full of unrelated data.

bash
node --version
npm --version
mkdir -p /tmp/deepseek-harness-quickstart
cd /tmp/deepseek-harness-quickstart
printf '# Harness quickstart\n\nThis file may be read but not edited.\n' > README.md
pwd

Launch the Web profile and understand the address

Run the official package with the web alias. The launcher auto-initializes the shipped Web profile on first use. In the installed production form, the Web runner serves http://127.0.0.1:3080 by default and prints its URL. Loopback binding means another machine cannot connect directly. The CLI intentionally rejects --host 0.0.0.0 today; do not work around that product boundary by inventing an unsupported flag.

bash
cd /tmp/deepseek-harness-quickstart
npx @deepseek-ai/dsh web

Open the printed URL in a browser on the same machine. If port 3080 is already occupied, ask the Web application for its current help before choosing a different port. Launcher flags come before application arguments, and flags after the web alias belong to the Web app. A named browser authority can be added through repeatable --trusted-host values, which participate in the /api browser-trust fence; this is not the same as binding to every interface.

bash
npx @deepseek-ai/dsh web --help
# Example only after confirming the current help:
npx @deepseek-ai/dsh web --port 3081

Observable success is a printed http://127.0.0.1 address, a loaded application shell, and no usage or boot error in the terminal. Leave that terminal open: it owns the host process and is the first place to inspect configuration, trust, and shutdown failures.

Store a DeepSeek credential through the Web settings flow

Open Settings → Models. The DeepSeek card exposes one API-key field. Enter the credential and save it. The provider becomes usable on the next request without restarting the server. The credential is write-only: after saving, the page receives a redacted descriptor rather than the literal value. The local credential provider stores the secret in $DSH_HOME/.credentials.yaml while the settings document keeps only its credential reference.

This separation matters. Model configuration can name apiKeyEnv or another reference without copying the key into every profile row. Provider adapters resolve credentials per operation, so a rotated value can reach the next request. The shipped deployment can also resolve credentials from inherited environment, the managed credential document, the invoking directory's .env, and the Harness-home .env in its documented precedence. Prefer the write-only settings path for this quickstart because it avoids exporting a secret into unrelated child processes.

text
Settings → Models → DeepSeek
1. Paste the credential into the write-only field.
2. Save.
3. Confirm the card shows a redacted configured state.
4. Do not expect the page to reveal the stored value.

Add and select the workspace before composing

Click Choose workspace, add /tmp/deepseek-harness-quickstart, and select it. The session composer remains unavailable until a workspace is selected. The workspace path is not decorative metadata: a new session records its cwd in the immutable SessionHeader, and sandbox policy uses that canonical path as the workspace root for calls in workspace-write mode.

The host-side workspace registry groups sessions and persists workspace ordering, but it does not inject workspace records into the model prompt or register model-facing tools. File access comes from the composed filesystem, shell, and tool providers. This distinction helps diagnose a confusing state: seeing a workspace in the sidebar does not prove that a particular session was created with that cwd. Confirm the selection before starting the session.

text
Choose workspace
Input: /tmp/deepseek-harness-quickstart
Action: Add, then Select
Expected UI: the composer becomes available
Expected session fact: cwd points to the selected directory

If the directory does not appear, verify that the dsh process can access it and that you entered an absolute path. If the composer stays disabled after selection, check the model picker next; both a usable model and workspace are required.

Select a model and a bounded permission preset

Configured providers appear in the model picker. Selecting a model also sets the default for future sessions. A session that has already sent a request retains the model recorded in its log. Changing the default later does not rewrite an active conversation. To compare two models fairly, start a new session for the second model rather than assuming a midstream selection changes all prior and subsequent request facts.

Keep the default workspace-write permission preset for the first run. That preset bundles workspace-write sandbox mode with an ask approval policy. Its default is pinned when a new session is created; changing General settings affects later sessions, not an existing one. workspace-write restricts file modifications to the session workspace and platform temporary roots, but it does not promise that reads, network access, or process visibility are confined. Use a workspace without sensitive readable material.

text
Session setup
Model: choose the configured DeepSeek route
Permission preset: workspace-write
Workspace: /tmp/deepseek-harness-quickstart
Create: a fresh session after all three selections are visible

Run a first task with verifiable evidence

A vague prompt such as ‘explain this project’ makes hallucination hard to separate from correct inspection. Ask for a small set of facts with explicit evidence and forbid modification. The workspace contains one known file, so you can compare the response directly with disk state and inspect whether any write tool ran.

text
Inspect this workspace without modifying files.
List every top-level entry, quote the first heading from README.md,
and explain which tool evidence supports each claim.

The expected answer names README.md and quotes ‘Harness quickstart.’ The trajectory should contain read operations and no successful mutation. Verify the file after the response rather than trusting the assistant's claim that it made no changes.

bash
cd /tmp/deepseek-harness-quickstart
find . -maxdepth 1 -type f -print
grep -n '^# Harness quickstart$' README.md
git diff --no-index /dev/null README.md || true

The last command displays the known fixture rather than proving immutability on its own. For a stronger check, record a digest before the task and compare it afterward. A matching digest, correct response, and read-only tool trace together form observable success criteria.

bash
shasum -a 256 README.md > /tmp/readme.before
# Run the prompt in the Web UI, then:
shasum -a 256 -c /tmp/readme.before

Verify persistence, reload, and session-owned choices

Refresh the browser after the task completes. The visible transcript should be reconstructed from durable session events rather than only client memory. User messages, assistant chunks, turn and step boundaries, and tool events belong to the append-only session vocabulary. The same stream supports resume, transcripts, telemetry, and persistence. If the conversation disappears, a successful final message was not enough to prove the runtime path you need.

Next, change the global default model in Settings without sending another request in the existing session. Open a new session and observe that it receives the new default, while the original session remains associated with the model recorded in its log. This confirms model stickiness and prevents accidental comparisons where two turns silently use different defaults.

text
Verification flow
1. Complete the read-only task in Session A.
2. Refresh and reopen Session A; confirm transcript and tool evidence.
3. Change the default model in Settings.
4. Create Session B; confirm the new default.
5. Reopen Session A; confirm its recorded model is unchanged.

Troubleshoot startup, model, workspace, and request failures by layer

If npx fails before a URL appears, confirm Node.js, npm registry access, and the exact package name. A CLI usage error points to an unsupported flag. A Web boot error after profile initialization belongs to composed configuration or artifacts. If the browser loads but /api requests are refused, inspect the printed authority and any trusted-host setting rather than changing the model.

If no model is selectable, save a provider first. MISSING_CREDENTIAL points to secret resolution. UNKNOWN_MODEL means the chosen id is not offered by current configuration. A provider 401 during model discovery points to the credential. If a custom model rejects an image, the declared input modalities and the endpoint's actual support disagree; remove the unsupported image claim and start a new session because the attachment remains in the old log.

If the composer is disabled, confirm both workspace and model selection. If a tool cannot write inside the workspace, inspect the session's pinned permission preset and canonical cwd. If it attempts an outside write, denial is a success of the boundary, not a reason to switch immediately to danger-full-access.

bash
npx @deepseek-ai/dsh --help
npx @deepseek-ai/dsh --profile web --dump-config > /tmp/web-resolved.yml
grep -E "webserver|llm|credentials|workspace|permission|sandbox" /tmp/web-resolved.yml
  • No URL: launcher, package retrieval, flag, or boot layer.
  • Page but no API: host trust or server layer.
  • No model: provider settings or credential layer.
  • No composer: model plus workspace selection layer.
  • Wrong tool behavior: session permission, sandbox root, or tool provider layer.

Shut down cleanly and preserve an evaluation record

Stop the host from its terminal. The CLI gives the plugin tree up to five seconds to dispose. The first SIGINT begins graceful drain and reports exit code 130; SIGTERM is the supervisor's normal stop request and exits zero. A second signal forces immediate exit. Wait for bounded disposal so persistence and watchers have an opportunity to close instead of treating every shutdown as an abrupt kill.

bash
# Interactive stop in the dsh terminal:
# press Ctrl+C once and wait for disposal

# Supervisor-style verification in a separate controlled run:
kill -TERM "$DSH_PID"
wait "$DSH_PID"

Record the package version, resolved profile dump, workspace path, provider id, selected model, permission preset, and the five success checks from the opening section. Do not archive literal credentials or an unreviewed session log. Session events can contain prompts, tool arguments, results, and workspace paths; explicitly enabled telemetry may export the same sensitive material because the shipped base has no redaction rule.

Your next step should follow the question you are trying to answer. Use source execution when you need to inspect or change plugins. Compare Web and headless when automation is the goal. Use the Python SDK when another program must own lifecycle and RunResult handling. Keep the quickstart workspace until you have reproduced the run, then remove it through your normal recoverable cleanup process.

Official sources

Continue in this category