Troubleshooting

Preserve the boundary

A diagnostic is not permission to bind publicly, disable Authelia, run as loca, expose /home, broaden the workspace, add a wildcard trusted host, or print credentials. Stop the service if diagnosis requires any of those changes.

Web and authentication

Symptom	Likely cause	Safe action
Authelia challenge repeats	Edge session, cookie, time, or forward-auth configuration problem	Diagnose the existing edge gate. Do not bypass it or expose port 52320.
Web shell loads but /api returns 401	Missing or stale upstream session cookie	Complete the current process launch-token exchange at https://deek.loca.zone, not the loopback origin.
Browser worked before a restart, then /api fails	A routine restart does not invalidate a valid cookie; the authority, cookie, or persisted signing credential changed or failed independently	Verify the public authority and managed credential state. Do not assume a fresh token exchange repairs the underlying change.
Token exchange fails only on the public host	Public authority is absent from the browser-trust fence, or nginx forwarded a different Host	Keep the exact service argument --trusted-host deek.loca.zone and preserve that host at the proxy. Do not add a wildcard.
A loopback cookie does not work publicly	Upstream binds cookies to normalized hostname and port	Exchange the token on the public HTTPS origin. Cookies are not portable between authorities.
Launch URL was disclosed	Launch-token credential incident	Restart to rotate the launch token. If token use is suspected, have the deployment owner use the approved credential-management procedure to rotate or delete the client-connection/browser-session record, then restart to revoke every browser cookie.

Static assets and non-/api routes are public in the upstream server model. The loca edge must gate the entire browser surface; a visible shell does not prove API authentication or isolation.

Build and startup

Symptom	Likely cause	Safe action
Profile boot reports missing host artifacts	Source dependencies exist but the repository build has not completed	Run pnpm run build from the reviewed source root, then promote a new immutable runtime copy.
Startup reports missing frontend or client-plugin bundles	The Web artifacts were not built	Rebuild; do not edit generated output by hand.
Browser UI is older than the source revision	pnpm dsh does not check artifact freshness	Rebuild and redeploy the same reviewed revision.
--host 0.0.0.0 exits with a usage error	Upstream intentionally refuses wildcard Web binding	Keep --host 127.0.0.1; nginx is the only public entry point.
Unit cannot write persistent state	StateDirectory=deek, DSH_HOME, or the workspace contract is wrong	Stop the service and repair the unit/state declaration. Never make the tree writable by loca or everyone.
State appears under another home	DSH_HOME=/var/lib/deek is missing or blank	Stop the service, restore the required environment, and reconcile any stray state without displaying credentials.

Use systemctl is-active deek.service and the listener check from Operations before opening secret-bearing logs. If journal inspection is unavoidable, use a restricted terminal and redact the entire launch-URL query before sharing any line.

Provider and model errors

Signal	Meaning	Action
MISSING_CREDENTIAL	The selected route cannot resolve its credential	Store the key through Settings → Models or repair its existing managed reference. Do not add the value to the unit.
UNKNOWN_MODEL	The recorded provider/model route no longer exists	Select a configured model or restore the intended provider definition.
Composer shows Select model and blocks input	A saved default points to a provider that was deleted	Select another configured model.
Model discovery returns 401	The provider rejected the current credential	Replace the key through the write-only Models UI. Do not print the old or new value.
A custom gateway rejects every request	Its OpenAI-compatible request shape differs	Review upstream’s provider compatibility fields; change only the documented route settings.
Existing session keeps the previous model	Models are recorded in the session after its first request	Start a new session when the new default must apply.

Provider changes take effect on the next request and normally need no service restart.

Workspace and permissions

Symptom	Likely cause	Safe action
New Web UI cannot compose	No workspace has been selected	Add and select only /var/lib/deek/workspace.
Intended file is outside the picker	It has not been staged into the dedicated workspace	Copy a reviewed, non-secret working set into the workspace through an operator-controlled process. Do not expose /home or /opt/deek/app.
Mutation is denied outside the workspace	The default workspace-write boundary is working	Move only the required disposable input into the workspace; do not switch to unrestricted permissions.
A read or network request reaches beyond the workspace	Upstream does not confine reads or network under workspace-write	Remove the resource from process visibility or block it at the host/network boundary. Approval settings are not a substitute.
A permission change has no effect on an open session	Stored General settings apply to later Web sessions	Create a new session after reviewing the setting.

Plugins and profiles

• A successful plugin add, remove, or update changes bundle membership on disk, but the running profile retains the bundle set from startup. Restart after an approved bundle change.
• Ordinary profile/home patch edits can hot-reload when the profile uses patchReload: live; still review the resulting composed configuration.
• An MCP server command and an external plugin execute as trusted host code outside the agent sandbox. Remove the package or patch rather than weakening the sandbox to make it work.
• The loca deployment does not permit ad hoc plugin installation into the live service state. Follow the reviewed immutable-release path in Plugin Model.

Escalation record

Capture only non-secret facts:

• deployed Git revision;
• unit active/inactive result;
• listener address and port;
• public HTTP status before authentication;
• exact error code or redacted message;
• browser authority used;
• whether failure began after a restart, update, provider change, or plugin change.

Never attach a launch URL, cookie, API key, credentials file, environment dump, raw startup journal, or user workspace content.