dsh startup flags: port, host, public URL, patches
dsh has two sets of startup flags: the launcher's own, written first, and the web app's, which must follow the profile selection. Miss that boundary and flags are silently ignored.
dsh flags: launcher flags and web app flags
The launcher parses its own flags and stops at the first token it does not recognize, handing the rest to the application.
| Form | Parsed by | Result |
|---|---|---|
dsh --help | Launcher | Launcher help |
dsh --profile web --help | Web app | Web flags, no start |
dsh --profile web --port 8080 | Web app | Starts on 8080 |
dsh --port 8080 | Launcher | Unintended usage |
dsh web is shorthand for dsh --profile web. The name must follow dsh directly, so when you also pass application flags, the long form is easier to get right.
With ownership clear, look at what the web app actually accepts.
Seven flags, and anything not on the list is not a web flag.
--host: bind one concrete local address;--port: listen port, 3080 by default;--no-open: skip the browser handoff for this run;--public-url: announce the externally visible root;--trusted-host: repeatable, declares trusted browser authorities;--tls-certand--tls-key: a certificate chain and an unencrypted key, always together.
To confirm what your build supports, run dsh --profile web --help. That output comes from the installed version, not from a webpage.
dsh web: changing the port
Write dsh --profile web --port 8080, with the flag after the profile.
- Check the target port with
lsof -i :8080; - Start with the flag in place;
- Read the bound address in the output and confirm 8080;
- Verify with
curl -I http://127.0.0.1:8080; - Put the full command into a script rather than trusting memory.
The port affects listening only, not stored data. Sessions stay in DSH_HOME and are not tied to a port.
dsh web: --host limits and running behind a proxy
--host takes one concrete local address and rejects wildcards; --host 0.0.0.0 exits with a usage error.
- Find local addresses with
hostname -ior the platform equivalent; - If several are printed, pass exactly one;
- Self-test with
curl -I http://<that address>:<port>; - Confirm the source network and firewall rules before sharing it.
Binding is not authorization. Exposing an address only lets connections arrive; authentication and Host/Origin checks still apply, so do not confuse reachability with public availability.
Serving other machines usually also means putting a reverse proxy in front.
--public-url tells the browser where the app lives; --trusted-host authorizes that name. They are not interchangeable.
- Set
--public-urlto the externally visible HTTPS root, including any proxy prefix; - Set
--trusted-hostto the hostname that appears in the browser; - If the proxy terminates TLS, do not also pass the certificate pair;
- Access once from the external address to confirm no origin rejection.
Certificate flags must be paired. One without the other is invalid configuration, and missing, unreadable, empty, or invalid files fail startup with no fallback to plain HTTP.
dsh flags versus patches
A flag beats a value written in a config row; between config rows, the later patch layer wins. The order is:
- Bundle-supplied patches;
- The profile's own
cordis.patch.yml; - The home-level patch under DSH_HOME;
- Each
--patchpassed on the command line, in argv order.
Two details cause most surprises. A patch replaces the entire config value for that row instead of deep-merging it, and a flag's precedence depends on a runtime expression in that row. Replace the row wholesale and the flag stops being read.
dsh startup logs and four common pitfalls
Normal starts are read in the terminal; failed starts have a file.
- When a required plugin fails to activate, the CLI prints the plugin and its stack first;
- It then lists plugins still waiting and the services they need;
- A full report lands under the DSH_HOME logs directory as
startup-<timestamp>-<uuid>.log; - The process exits with status 1 even if handles remain open;
- The report is not redacted and may include configuration or credential fragments.
DSH_HOME defaults to ~/.dsh. If you moved it, the logs moved with it.
The log handles individual cases; the four pitfalls below cover most flag misuse.
Flag problems cluster around position, wildcards, patch overrides, and pairing.
| Symptom | Cause | Fix |
|---|---|---|
--port ignored | Placed before the profile boundary | Move it after --profile web |
| Usage error on start | --host 0.0.0.0 | Pass a concrete local address |
| Proxy rejects requests | public-url without trusted-host | Add --trusted-host |
| HTTPS fails to start | Only one certificate flag | Supply both |
Change one variable per retest. Altering port and host together makes a rejection impossible to attribute.
dsh next steps
Confirm flag placement before discussing binding and proxies. For layered startup triage, read the dsh startup decision tree. For LAN access options, read dsh web on a local network. For command lookup, read the dsh command cheatsheet. For custom profiles, read configuring a custom profile.
Sources: dsh CLI reference, dsh CLI README, DeepSeek Harness docs
FAQ
The dsh launcher only parses flags it recognizes, so --port belongs after the profile selection. The first unrecognized token starts application arguments, which are handed to the profile. Ahead of the profile, the launcher never parses --port.
The dsh web --host flag accepts one concrete local address and refuses wildcard addresses. To serve other machines, bind the specific interface address that clients reach, or keep loopback and terminate traffic at a reverse proxy.
A dsh flag is overridden when it sits before the profile boundary or when a patch writes a literal into that config row. Confirm the flag position first, then check whether that config row was replaced with a literal. Patches replace the whole config value rather than deep-merging it, which can remove the runtime expression that reads the flag.
When a required plugin fails to activate, the CLI prints the plugin and stack, then writes a full report to a single startup-<timestamp>-<uuid>.log under the logs directory in DSH_HOME, exiting with status 1. The report is not redacted.
Related Terms
- launcher flag
- A launcher flag is parsed by dsh itself, must appear near the start of the command, and selects a profile or a management mode such as plugin operations.— dsh CLI reference
- application argument
- An application argument is everything from the first unrecognized token onward, handed unchanged to the profile application that parses it.— dsh CLI reference
- patch layer
- A patch layer is an overlay applied to the config tree after bundle patches, profile patches, and home patches, with later layers taking precedence.— dsh CLI reference
- public-url
- public-url is the application root announced to browsers, possibly behind a proxy prefix, but it grants no trust by itself.— dsh CLI reference
Sources
- dsh CLI reference· deepseek-ai
- dsh CLI README· deepseek-ai
- DeepSeek Harness docs· deepseek-harness