Logs and troubleshooting

Agents: claude, codex, opencode · On: desktop

Every unit logs to the journal. Three commands cover almost everything, and there are four rules that explain most of the confusing failures.

Why you would use it

The app came back wrong after an update, a tab will not open, or the phone is showing a version you replaced an hour ago.

How to use it

journalctl --user -u v-code -f
journalctl --user -u v-code-tunnel -f
journalctl --user -u v-code-voice -f

bash install.sh status                       # all installed units, token redacted
curl -s localhost:3445/health                # ok, authRequired, voice, threads
systemctl --user restart v-code   # from a terminal only

What you see

Boot lines from server.js:

VCode on http://127.0.0.1:3445/
state /home/you/.local/state/v-code/workbench/threads
auth: OFF (loopback only). Set AUTH_TOKEN to require a token. — only when there is no token

Refusals, one line then exit 1:

[v-code] refusing to start: VCODE_REQUIRE_AUTH=1 but AUTH_TOKEN is empty.
[v-code] VCODE_PEERS: "<entry>" must be "name|url"
port 3445 is already in use — another VCode server is running.

Running lines: error <status> <METHOD> <path> for anything that failed, with long path segments masked, and parked <thread-id> after N min idle when the memory reaper stops a tab.

Options and settings

Rule	Why
Never restart `v-code` from inside a VCode thread	The restart kills the agent turn that issued the command. Run it from a terminal or over ssh
Restart after any merge that adds a `<script src>`	Static files serve from the repo directory, so disk serves the new `index.html` while the running process still 404s the new route
Bump `VERSION` in `public/sw.js` with any change to the shell	Installed phones serve the cached shell until the version changes, restart or not. The bump shows the update button (`#update-ready`) in the top bar — see update-to-a-new-build
`bash install.sh update` does the first two for you	It restarts every active unit at the end

The shell, for the VERSION rule, is public/index.html, public/styles.css, the public/*.js scripts, lib/derive.js and lib/tab-order.js.

Limits and known gaps

A version split looks like a broken app, not a stale one. The symptom is a shell that loads — composer visible — with no threads, and a console showing GET /lib/tab-order.js → 404 then TypeError: Cannot destructure property 'sortThreads' of 'globalThis.VCodeTabOrder'. The fix is systemctl --user restart v-code.service. Clients that loaded the page mid-split need one fresh tab. Quick check: curl -o /dev/null -w '%{http_code}\n' every <script src="/lib/*.js"> in public/index.html against the live port, not against the tree.
A dead voice sidecar still shows the mic. /health.voice reports the variable, not a service that answers, so with v-code-voice.service down every clip comes back a 502 with the voice service is not answering in a toast.
Rolling back past the release that added a settings key loses the other settings. settings.update() writes the whole object, so after any save the file carries the new key; the older validator rejects the unknown key and the whole file with it. The boot logs settings.json unreadable, using defaults: unknown setting: voice and comes up on defaults for everything. Nothing is written back until the next save, so the file still holds the old values — delete the new key before rolling back.
npm test reports a varying total, because --test-force-exit cuts off files still in flight once the runner drains. fail 0 is the signal; the count is not. To count, run the files individually and sum.
A test run that appears to hang after passing is node's global fetch keeping keep-alive sockets open, so server.close() never drains. That is what --test-force-exit in the npm script is for. Do not read it as a logic failure.
install.sh status redacts the tunnel token from anything it prints, but the process table still carries it.