Skip to content

feat: serve under a URL path prefix with --base-path - #61624

Draft
fabiovincenzi wants to merge 15 commits into
anomalyco:devfrom
fabiovincenzi:server-base-path
Draft

fabiovincenzi wants to merge 15 commits into
anomalyco:devfrom
fabiovincenzi:server-base-path

Conversation

@fabiovincenzi

Copy link
Copy Markdown

Issue for this PR

Closes #7624

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

Depends on #60559, so it's a draft until that merges. Until then the diff also includes its two commits.

Adds opencode serve --base-path /opencode, so the server and web app can run behind a reverse proxy under a path prefix.

  • The server strips the prefix before routing, redirects /opencode to /opencode/ and returns 404 outside it.
  • The server adds the prefix to index.html in a <meta> tag. Scripts and styles now load their dependencies with relative URLs
  • Under a prefix the app uses a small router that hides the prefix from the rest of the app, because Solid's base doesn't change what useLocation() returns.
  • Pairing works under the prefix, and the session cookie is scoped to it.

Open questions:

  • Paths outside the prefix return 404, so --service is rejected, since local clients reach the managed service at its root. Should the root keep working too?
  • The service worker isn't registered under a prefix, because its exclusions are built for the root.

Replaces #28326, which targeted V1.

How did you verify your code works?

New tests in packages/server (base-path.test.ts), packages/cli (web-ui.test.ts) and packages/app (base-path-router.test.ts, pairing.test.ts). Each one fails without its change.

Manually behind nginx with the config from the docs: pages and reloads, the event stream and a terminal. Through a small test proxy: every lazy-loaded chunk and pairing.

Visual

N/A

Screenshots / recordings

N/A, no visual change.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

@github-actions

github-actions Bot commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Hey! Your PR title Server base path doesn't follow conventional commit format.

Please update it to start with one of:

  • feat: or feat(scope): new feature
  • fix: or fix(scope): bug fix
  • docs: or docs(scope): documentation changes
  • chore: or chore(scope): maintenance tasks
  • refactor: or refactor(scope): code refactoring
  • test: or test(scope): adding or updating tests

Where scope is the package name (e.g., app, desktop, opencode).

See CONTRIBUTING.md for details.

@fabiovincenzi fabiovincenzi changed the title Server base path feat: serve under a URL path prefix with --base-path Nov 4, 2026
@monolith-james

Copy link
Copy Markdown

We'd like to use this to run OpenCode inside marimohub, the self-hosted marimo server. It already runs VS Code next to the notebook through an authenticated proxy at /surface-proxy/<signed-token>/<surface>/. OpenCode is currently limited to subdomain exposure because of its root-relative paths, so --base-path is the missing piece for us.

On the open questions:

  • A 404 outside the prefix is fine for us. The proxy only forwards paths under the prefix, and we don't use --service.
  • We don't need the service worker under a prefix.

Things we'd depend on:

  • The prefix is a signed token per session, shaped like /surface-proxy/<project-id>.<session-id>.<base64url-signature>/opencode. That passes normalize as written. Please keep ., _ and - allowed in segments.
  • The event stream and the terminal WebSocket under the prefix, which you mention checking behind nginx.

One question: does the app assume the browser's path matches the prefix the server sees? A proxy in front may strip an outer prefix first (for example, the hub served under /hub). The browser would then be at /hub/surface-proxy/… while OpenCode sees /surface-proxy/…. Relative asset URLs would still resolve, but I wasn't sure about the router or the cookie path.

Happy to test a build behind marimohub's proxy once #60559 lands.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE]: Base path / prefix routing support

2 participants