Support running smallweb in Codespaces/Codesandbox/cloud IDEs: HTTP-only mode, proxy-aware base URLs

[public-rant]

Many developers use cloud IDEs such as GitHub Codespaces or Codesandbox to test and develop smallweb apps. These environments enforce HTTPS via their own reverse proxies and generate preview domains like:

• Codespaces: https://fuzzy-space-waddle-abc123-8080.app.github.dev
• Codesandbox: https://abc123-8080.csb.app
• Gitpod: https://8080-workspace-abc123.ws-eu54.gitpod.io

All client requests are routed to the exposed port in the development container (which typically serves plain HTTP). The platform then terminates HTTPS, injects its own certificate, and forwards traffic to the container. This brings a few challenges:

Current Issues:

• If smallweb serves HTTPS internally, the cert will never match the external preview domain, leading to browser errors and configuration complexity.
• Apps may construct links or OAuth redirect URIs using localhost or the internal port, which will fail because the user sees the public preview domain.
• Cloud IDE proxies forward headers such as Host and X-Forwarded-Proto for reconstructing the correct external base URL, but smallweb may not always leverage these for correct user links or redirects.
• OAuth flows and third-party integrations are particularly affected by incorrect or inconsistent base URL computation.

Feature Request:

• Add a config flag (e.g. --env codespace/--env sandbox or via config file) to:
  • Always run smallweb?s internal server in plain HTTP mode in known cloud IDE environments (optionally emit a notice about HTTPS being handled externally).
  • Correctly reconstruct all external links and OAuth redirect URIs using X-Forwarded-Proto and Host headers.
  • Document guidelines for using smallweb in Codespaces/Codesandbox/Gitpod-like environments (including environment variable tips).
• Auto-detection Suggestion: in the future, support auto-detecting known environments using variables such as:
  • CODESPACES (GitHub Codespaces)
  • CODESANDBOX_HOST (Codesandbox)
  • GITPOD_WORKSPACE_URL (Gitpod)

Proposed Example Config:

{
  "cloudIDE": true,
  "trustProxyHeaders": true
}

(open to other config names/formats matching project standards)

Benefits:

• Eases onboarding and reduces surprises for cloud IDE users.
• Prevents TLS/cert errors and broken links/redirects in supported workflows.
• Makes smallweb robust and portable in modern cloud-based development scenarios.

Planned and Possible Future Enhancements:

• Automatic environment detection based on env vars (for "it just works" experience).
• Optionally display a banner or log notice when running in a detected cloud IDE environment.
• Automatic fallback to best-practice base URL/path heuristics for unfamiliar proxy environments.

References:

• Many cloud IDEs forward these headers for reconstructing user-facing URLs: Host, X-Forwarded-Proto, X-Forwarded-Host
• Relevant for OAuth, OpenID Connect, SSO, and other flows sensitive to canonical URLs.

I'm happy to help clarify use-cases, share more environment examples, or test any proposed solution. Thank you for your work on smallweb!

[pomdtr]

A good way to handle this is to setup a mutagen sync between your codespace and your smallweb folder.

See https://github.com/pomdtr/smallweb-codespace-template for an example (still needs some work).

It allows your edits to be instantly reflected on your live instance of smallweb.

[public-rant]

Thanks, that workaround for live sync does make sense and is handy for persistent environments.

After rereading, I realized my main concern here is a bit different: since Codesandbox/Codespaces don’t support wildcard subdomains, the subdomain-per-app model can’t actually be previewed there at all. Supporting path-based routing (e.g. /foo) would make it possible to generate isolated, shareable previews in these environments—without needing to sync to a prod/staging instance. Access control via private would still apply either way.

Just wanted to clarify since I originally framed it mostly as a proxy/HTTPS issue rather than a routing one.

[pomdtr]

I see. Sadly subpaths are quite differents to subdomains, so switching from one model to the other would break existing apps (ex: apps would need to handle the subpath in their routing, cookies would not be isolated)...

One motivation for building smallweb was the ability to "develop in prod". Oftentimes, when I want a dev env, I just create a new folder with a -dev suffix. Then, since my smallweb folder is synced to my laptop using mutagen, I'm just able to locally edit the app.