Fix dsh web 'Authentication required' token wahala

Wetin dis dsh web 'Authentication required' screen mean

Di short answer na dis: dsh web dey print one URL wey carry session token inside am, and na only that complete URL fit sign your browser in. When di UI tell you say authentication dey required make you reopen di URL wey dsh web print, e mean say your browser no hold di session wey di server dey expect. No password dey for dis place, and no login form dey. Na di token wey dey inside di printed URL dey open door.

So di work na simple. Go back go collect di exact line wey di running process print, come open am whole whole, query string and all. Any road wey chop that query string go carry you come back dis same screen.

Why dsh web dey put token inside di URL at all

Di web server dey authenticate every request since dsh 0.1.2-rc.1. As of September 2026 dsh still dey developer preview and e dey change fast, so make you confirm with your own install instead of trusting wetin any blog write, including dis one. Run dsh web --help and read wetin your own version print.

Wetin di server dey do na dis. Every time di process start, e dey create one random token, keep am inside memory, come print am once inside di root URL. Di shape na like http://127.0.0.1:3080/?token=.... Di token no dey save for disk, and e dey change every single time di process start again.

When you open that URL, di server collect di token come give your browser one session cookie, den redirect you go plain /. After that one trade, na di cookie dey carry you. Di cookie na HttpOnly, SameSite=Strict, Path=/, host only, and by default e get like 30 days max age. Every other request wey di UI dey fire, di API calls and di WebSocket connection, dey need that cookie. No cookie, di server go answer 401, and na dat 401 di page dey show you as di authentication message.

Two things from dat design really matter. First, di cookie dey tied to di exact hostname plus port wey you take collect am, so cookie wey you get for 127.0.0.1:3080 no go work for 127.0.0.1:9090 or for any other hostname. Second, no flag dey wey go turn off di authentication, so if you dey find am you go just waste time.

Which road dey carry people come dis screen

Every cause na di same cause wearing different cloth: di token never reach di browser, or di cookie wey e for produce no dey there again.

• You copy only di host and di port comot for terminal. http://127.0.0.1:3080 alone no carry token, so di server no sabi you at all.
• You open one old bookmark or one tab wey don tey. Di bookmark hold yesterday own URL, and dat token don die since di process restart.
• Di cookie don expire, or you clear browser data, or you dey use incognito window wey dey throway cookie di moment you close am.
• You move go another browser, another browser profile, or another laptop. Cookie no dey travel between dem, so each one need im own trip through di token URL.
• One reverse proxy, one link shortener, or one chat app chop di ?token=... part. Plenty proxy config dey forward path and dey drop query string, and some dey redirect /?token=... go / before di server ever see di token.
• Di process restart and dis particular browser never trade token for cookie before. Note say cookie wey never expire fit still work after restart on di same host and port, so restart alone no dey always break am. Na browser wey never collect cookie for dat address dey feel am pass.
• You click di link from inside another web page. Because di cookie na SameSite=Strict, browser fit refuse to send am on cross site navigation. Type di address yourself, or use your own bookmark.

How to collect di correct URL again, without guessing token

Make I talk am plain: you no fit guess di token, and you no suppose try. Na random value, so anything wey you build by hand na waste of time. Di only correct move na to read am from di process wey print am.

If di terminal wey you run dsh web inside still dey open, scroll up go find di line. For tmux you fit search di scrollback directly:

tmux capture-pane -p -S -3000 -t dsh | grep -i token

If you dey run am under systemd, di line dey inside di journal, because whatever di process print to stdout dey land there. Change di unit name to your own:

journalctl -u dsh-web.service -o cat --no-pager | grep -i 'token='

Use di newest line wey come out after di most recent start. If plenty start dey inside di journal, di older ones carry token wey don die already, so dem go still give you di same screen.

If di output don scroll comot and di journal no keep am, no vex. Just restart di process, because fresh process dey print fresh URL:

sudo systemctl restart dsh-web.service
journalctl -u dsh-web.service -o cat --no-pager -n 30

If you dey run dsh for background on your VPS and you never set am up properly, run am as a proper systemd unit so di printed URL go dey inside di journal every time instead of dying with your SSH session. Dat one alone dey finish dis problem for most people.

One warning before you move: di token na credential. No paste am inside GitHub issue, no put am inside screenshot, no drop am inside group chat. Anybody wey get dat URL and fit reach di port fit enter your agent session.

SSH tunnel dey keep di token, careless proxy no dey

Di UI dey bind to loopback on purpose, and why e dey answer only for 127.0.0.1:3080 na im own full topic. Wetin concern us here na one small thing: di way you take reach di UI fit keep di token or fit spoil am.

SSH tunnel dey keep am. Di tunnel na raw TCP pipe. E no dey read HTTP at all, so e no fit chop query string and e no fit rewrite header.

ssh -N -L 3080:127.0.0.1:3080 youruser@your-vps

With dat tunnel up, open di exact URL wey di server print, token and all, for your laptop browser. Use di same local port as di remote one so di address match wetin di server dey expect, because di cookie tie to hostname plus port. Di full setup dey inside how to open di dsh web UI wey dey run for VPS. If di SSH part sef dey fail before you reach browser, clear di publickey denied error first.

Reverse proxy na di opposite side. Nginx or Caddy config wey person write quick quick fit drop di query string, fit redirect /?token=... go /, or fit show different hostname to di browser so di cookie no match. Then you go dey blame dsh for wetin di proxy do.

One useful detail for dat case: if wetin you see na 403 and no be 401, na different check dey fail. 403 dey come from di Host and Origin validation, no be from missing session. Dat one dey point straight at proxy wey dey rewrite headers, no be at your token.

Wetin to check when e still no gree

First confirm say di same process wey print dat token still dey run and still dey hold di port:

ss -ltnp | grep 3080

If nothing dey listen, di 401 go confuse you well well, because your browser fit dey talk to something else entirely. Check whether di port really open before you blame di token.

If you wan throway every session wey exist, including one wey somebody else fit don collect, delete di client-connection/browser-session record inside $DSH_HOME/.credentials.yaml, restart di process, come open di fresh URL once. Every old cookie go dead immediately.

And if dsh sef no dey start well, or e begin misbehave after upgrade, na different road be dat. Di install and version errors cover dat side.

Di habit wey go stop dis wahala from repeating

Copy di whole URL. No be di host, no be di port, di whole thing including ?token=. Dat one sentence na almost 90 percent of dis problem.

Keep one bookmark of http://127.0.0.1:3080/ for di browser wey already carry di cookie, and go collect fresh token URL any time you use new browser or new machine. Di bookmark wey carry old token no dey useful, because dat token don die.

Di last one heavy pass di others: no open di UI to di open internet because you wan dodge token prompt. Di CLI sef dey reject --host 0.0.0.0, and na correct decision. Di web UI dey drive one agent wey fit run command inside your files. Tunnel am, no publish am.

FAQ

Wetin dis dsh web authentication required message really mean?

E mean say di request wey your browser send no carry di session cookie wey di server dey expect, so di server answer 401. Na di token inside di URL wey dsh web print dey produce dat cookie, one time per browser. Open di complete printed URL, query string and all, and di server go set di cookie come redirect you go di normal page.

I don lose di URL wey dsh web print. How I go take see am again?

Check di terminal scrollback first, or check di journal if e dey run under systemd, with something like journalctl -u dsh-web.service -o cat --no-pager | grep -i 'token='. Use di newest one, because di token dey change every process start. If e no dey anywhere again, restart di process and read di fresh line wey e print. No try to guess di token, e no go work.

Why di token work for my laptop but e no dey work for my phone?

Because di cookie na host only and e tie to di exact hostname and port. Each browser, each browser profile, and each device need im own trip through di token URL. Incognito window sef dey throway di cookie when you close am, so e go ask you again di next time you open am.

Restart go kill my session?

Not automatically. Di token dey change every start, but cookie wey never expire fit still work for di same hostname and port. You go only feel di restart if dat browser never collect cookie for dat address before, or di cookie don expire, or you don delete di browser session record and restart.