feat(app): support path-only hrefs for multi-hostname access

[mairas]

Motivation

We run Homarr as the home dashboard of a small Linux distribution (HaLOS) where Traefik fronts a set of containerized apps and exposes each one at a distinct path under the same origin (/cockpit/, /grafana/, /signalk-server/, etc.), with Authelia providing SSO across them.

A given device can be reached on multiple hostnames in different contexts: locally over mDNS as halos.local, and remotely over a VPN as something like halos.example.com. Our Traefik and SSO setup copes with both — TLS SANs, Authelia per-host cookies, and OIDC redirect URIs all adapt per request — but Homarr does not. App hrefs must be absolute URLs today, so a card created while reaching the dashboard at halos.local permanently links to https://halos.local/cockpit/. Clicking it from the VPN jumps the browser to a hostname that doesn't resolve in that context.

Path-only hrefs (/cockpit/) fix this cleanly: the browser resolves them against the current origin natively, so the same card works under every hostname the dashboard answers on. The change is purely additive — existing absolute hrefs are unaffected at every call site.

What changes

1. Schema relaxation — packages/validation/src/app.ts

appHrefSchema now accepts either:

• An absolute URL (existing behavior, byte-identical), OR
• A path-only form: /[^/]... — must start with a single forward slash followed by a non-slash character.

Path-only branch rejects:

• javascript: and other dangerous schemes (existing protection preserved by branch ordering).
• Protocol-relative hrefs (//host/...).
• Single-slash root (/) — too ambiguous to be a useful link target.
• Consecutive slashes mid-path (/foo//bar) — defends against accidental URL-parsing surprises in downstream consumers.
• Backslashes anywhere in the path.
• Whitespace and JavaScript \s characters anywhere in the path.
• C0/C1 control characters.
• Unicode zero-width, bidi, and formatting characters anywhere in the path (display-spoofing protection — paths like /admin‮‭ that visually resemble /admin but route differently).

Empty-string-to-null transform behavior is preserved (existing).

2. Server-side resolver — packages/common/src/url.ts

New resolveServerUrl(app) helper centralizes the existing pingUrl ?? href pattern:

function resolveServerUrl(app: { href: string | null; pingUrl: string | null }): string | null {
  if (app.pingUrl) return app.pingUrl;          // step 1 — explicit override
  if (isAbsoluteUrl(app.href)) return app.href; // step 2 — existing behavior
  return null;                                   // step 3 — path-only without pingUrl
}

Design choice: path-only hrefs intentionally resolve to null server-side. Path-only hrefs are a browser-resolved form. The server has no canonical hostname for an app whose href is path-only, and must not synthesize one from request headers — that would be a header-spoofing / SSRF vector (a malicious client setting x-forwarded-host: internal.target could redirect server-side fetches arbitrarily).

An earlier draft of this resolver expanded path-only hrefs against extractBaseUrlFromHeaders(headers). We dropped that branch on review — it adds an attack surface for a feature path-only-href apps don't actually need. Apps that require server-side coverage under multi-hostname deployments should set an explicit pingUrl.

3. Ping widget — packages/api/src/router/widgets/app.ts + packages/widgets/src/app/{component,ping/ping-indicator}.tsx

The pingUrl ?? href pattern in the router is routed through resolveServerUrl. When it returns null (path-only without explicit pingUrl), the router responds with a tRPC CONFLICT error instead of attempting a fetch.

Client-side: switch from useSuspenseQuery to useQuery. The previous indicator used useSuspenseQuery wrapped in a <Suspense> boundary in component.tsx. With Suspense, a tRPC error propagates to the nearest error boundary — which would treat the new "no ping URL available" CONFLICT response as a render-breaking error rather than the expected absence it actually is. The refactor:

• ping-indicator.tsx: useSuspenseQuery → useQuery with retry: false. Reads query.data / query.error directly. While loading or pending data, renders the blue IconLoader dot inline. On CONFLICT (path-only without pingUrl), renders a permanent blue IconLoader dot with the server's error message as tooltip — an explicit indeterminate state. Other tRPC errors (FORBIDDEN, NOT_FOUND, etc.) are re-thrown so the widget error boundary handles them as before.
• component.tsx: drops the <Suspense fallback={<PingDot icon={IconLoader}…/>}> wrapper since the loader is now handled inline by the indicator.

Net behavior: existing apps with absolute href / explicit pingUrl render byte-identically to today (loader → dot transition is now in the indicator instead of via Suspense, but visually the same). Path-only-without-pingUrl apps display the indeterminate blue loader dot indefinitely rather than tripping the widget error boundary — visually communicating "ping not configured" without breaking the card.

4. Integration middleware — packages/api/src/middlewares/integration.ts

externalUrl: rest.app?.href ?? null is replaced with externalUrl: resolveServerUrl(rest.app). This collapses path-only hrefs to null, letting the existing externalUrl ?? integration.url fallback at packages/integrations/src/base/integration.ts:85 take over.

Without this, integrations bound to path-only-href apps crash at runtime via new URL("/cockpit/" + path) → TypeError [ERR_INVALID_URL].

5. Bookmarks widget — packages/widgets/src/bookmarks/sub-label.ts

Extracted getHrefSubLabel helper. Branch-free given schema-validated inputs:

• Absolute href → render hostname (docs.example.com).
• Path-only href → render trailing-slash-trimmed path (/cockpit/ → /cockpit).
• Null → empty.

Backward compatibility

Every change is additive:

• Schema: existing absolute-URL inputs continue to validate identically; the path-only branch is an OR alternative.
• Resolver: for apps with explicit pingUrl or absolute href, the resolver returns the same string today's pingUrl ?? href pattern would. The new null case is reachable only for path-only hrefs without pingUrl — a state that is impossible under the old schema.
• Bookmarks widget: previously rendered new URL(app.href).hostname; the new helper produces the same hostname for all currently-valid hrefs.
• Integration middleware: previously could only see absolute hrefs; the resolver returns those identically.

There is no migration; existing data continues to validate and render unchanged.

Tests

• packages/validation/src/test/app.spec.ts — 33 schema cases: 12 acceptance, 21 rejection (backslash, whitespace, control chars, zero-width / bidi / formatting, consecutive slashes, javascript:, protocol-relative, bare strings, single-slash root).
• packages/common/src/test/url.spec.ts — 11 resolver cases.
• packages/widgets/src/bookmarks/test/sub-label.spec.ts — 10 sub-label render cases.
• packages/api/src/router/test/widgets/app.spec.ts — 3 router-level ping cases (path-only-without-pingUrl CONFLICT, path-only-with-pingUrl, absolute-href passthrough).

PR template checklist

• Builds without warnings or errors (pnpm build, autofix with pnpm format:fix)
• Pull request targets dev branch
• Commits follow the conventional commits guideline
• No shorthand variable names are used (eg. x, y, i or any abbrevation)
• Documentation is up to date. Create a pull request here.

Documentation: a docs PR against homarr-labs/documentation is planned to cover when and how to use path-only hrefs. Holding off on writing it until this PR has had initial review — that way any naming, behavior, or scope adjustments requested here flow through cleanly to the docs without rework.

[deepsource-io]

DeepSource Code Review

We reviewed changes in b94d2f1...7b45675 on this pull request. Below is the summary for the review, and you can see the individual issues we found as inline review comments.

See full review on DeepSource ↗

PR Report Card

Overall Grade

Security   Reliability   Complexity   Hygiene

Code Review Summary

Analyzer	Status	Updated (UTC)	Details
JavaScript		Apr 30, 2026 12:25p.m.	Review ↗

---

Important

AI Review is run only on demand for your team. We're only showing results of static analysis review right now. To trigger AI Review, comment @deepsourcebot review on this thread.

[Meierschlumpf]

Hey, thanks for your contribution we'll review and discuss this change in the team. If I understand it correctly you were able to configure Homarr to use subpaths https://halos.local/homar/ how did you do that?

[mairas]

Hey, thanks for your contribution we'll review and discuss this change in the team. If I understand it correctly you were able to configure Homarr to use subpaths https://halos.local/homar/ how did you do that?

Thanks!

Homarr is the main landing page on the device, so it's always at https://hostname.local/, not on a sub-path. Was that what you were asking?

The container apps are exposed to subpaths, e.g. https://hostname.local/cockpit/, but Traefik just 302 redirects to the exposed ports such as https://hostname.local:9090/ because many of the apps don't like to live at sub-paths.

[Meierschlumpf]

Oh makes sense (yes that is what I meant)
We actually also do not support subpaths because the web framework we're using only supports them when specified before build

[Meierschlumpf]

I'll take a look at this pr later tonight, sorry for the delay

[Meierschlumpf]

I think here we can actually keep the app?.href ?? null because it is used on the client. Otherwise it will use the pingUrl. Same below

[mairas]

Claude Code wanted to push back because externalUrl is also used server-side. I'm not sure I can completely follow the logic -- Claude's response is below. I'll implement accordingly. If you disagree, I'll revert. :-)

---

Good catch — externalUrl does flow back to the client through super.externalUrl(...).toString() in Jellyfin, Emby, Sonarr/Radarr/Readarr, Overseerr, Nextcloud and Ntfy, so for path-only-bound apps we genuinely want the path to pass through, not be collapsed to null.

The literal app?.href ?? null revert crashes, though: externalUrl is also consumed server-side in packages/integrations/src/base/integration.ts:85 (new URL(${baseUrl}${path})), and a path-only base like /cockpit/ throws Invalid URL. So I'd like to fix this properly rather than swap one crash for another.

Plan:

1. Teach createUrl to handle path-only bases — when inputUrl is path-only, return a small RenderablePath shim (toString() / pathname / hostname) instead of constructing a URL. 17 of 19 callers just .toString() the result; the two outliers (ntfy-integration.ts:57 reading .hostname/.pathname, overseerr-integration.ts:319 returning up to a .toString() caller) still behave sensibly.
2. Revert this middleware to app?.href ?? null at both call sites (70 and 132) as you suggested — safe once createUrl handles path-only.
3. Also patch packages/request-handler/src/lib/cached-request-integration-job-handler.ts:97, same app?.href ?? null pattern, same crash risk via the same code path. Pre-existing miss in our PR, surfaced while looking at this.

Net effect: integrations bound to path-only-href apps render their hrefs against the user's current origin, instead of falling back to integration.url (the server-internal address). Materially better for the multi-hostname use case.

resolveServerUrl stays in the ping router — the server genuinely can't ping a hostless URL, so CONFLICT is still right there. Pushing the change in a follow-up commit shortly.

[mairas]

Implemented. I'll leave the conversation open for your verification.

[mairas]

I'll take a look at this pr later tonight, sorry for the delay

No worries, real life intervenes etc. I'll go through your comments. They don't seem to bad. :-)

[dokploy-homarr-labs]

🚨 Preview Deployment Blocked - Security Protection

Your pull request was blocked from triggering preview deployments

Why was this blocked?

• User: mairas
• Repository: homarr
• Permission Level: read
• Required Level: write, maintain, or admin

How to resolve this:

Option 1: Get Collaborator Access (Recommended)
Ask a repository maintainer to invite you as a collaborator with write permissions or higher.

Option 2: Request Permission Override
Ask a repository administrator to disable security validation for this specific application if appropriate.

For Repository Administrators:

To disable this security check (⚠️ not recommended for public repositories):
Enter to preview settings and disable the security check.

---

This security measure protects against malicious code execution in preview deployments. Only trusted collaborators should have the ability to trigger deployments.

🛡️ Learn more about this security feature

This protection prevents unauthorized users from:

• Executing malicious code on the deployment server
• Accessing environment variables and secrets
• Potentially compromising the infrastructure

Preview deployments are powerful but require trust. Only users with repository write access can trigger them.

[Meierschlumpf]

Only add translation for locale en.json, all other languages are translated on crowdin by the community

[mairas]

Reverted the translations.

[Meierschlumpf]

IMO we should make it more explicit what the externalUrl and url are. Therefore I'm currently working on some nice typing improvements

[mairas]

IMO we should make it more explicit what the externalUrl and url are. Therefore I'm currently working on some nice typing improvements

So, in practice - I should wait and then rebase and refactor to use the new types?

[Meierschlumpf]

I would push my changes into your branch containing the type changes and then we can review it again and if okay, merge it

[Meierschlumpf]

Okay nevermind I don't have access to your fork, can you give me access?

[mairas]

Okay nevermind I don't have access to your fork, can you give me access?

Eh. I'm stumped - I usually tick the box while creating the PR, but now that it's not there, I can't find it... Gimme a moment.

[mairas]

Okay nevermind I don't have access to your fork, can you give me access?

Looks like I can't:

  Caveats:
  - If the head branch is on an organization fork (e.g., hatlabs/homarr), GitHub disables this option — org-owned forks don't support
  maintainer edits regardless of the checkbox. Workaround: push the branch to a personal fork and open the PR from there.

I can reopen the PR from my personal namespace but that'll of course wipe the comments so far.

[Meierschlumpf]

Hmm understood, no I think we can keep this open. I'll look into it tomorrow how we get my changes to you, for today I'll leave. See you soon

[mairas]

Hmm understood, no I think we can keep this open. I'll look into it tomorrow how we get my changes to you, for today I'll leave. See you soon

Pull this PR branch into a branch on another fork and do your edits there, then comment here and ask me to pull from that fork.

[Meierschlumpf]

I've created a PR on hatlabs#4