feat: base path support

[hsteude]

Add support for running OpenCode behind a reverse proxy with a configurable base path prefix (e.g., /myapp/)

Fixesthis issue.

Why

When deploying OpenCode with path-based routing, the application needs to serve assets and handle routing under a URL prefix. Without this, OpenCode can only run at the root path.

What it does

• Adds --base-path CLI option, OPENCODE_BASE_PATH env var, and server.basePath config
• Rewrites HTML/JS/CSS responses at runtime to include the base path
• Wraps history.pushState/replaceState to prepend base path to URLs

Design decisions

Runtime rewriting: We rewrite content at runtime because the frontend is proxied from app.opencode.ai and we don't control the build.

Regex-based Vite patching: Vite bakes the base path into a function at build time (function(t){return"/"+t}). Since we don't know the base path until runtime, we patch this via regex. It's not great, but the only alternative would require rebuilding the frontend for each deployment.

Double mounting: The app is mounted at both basePath AND / because some reverse proxies strip the path before forwarding. Without this, requests would 404.

No CSP with basePath: We inject inline scripts for the history wrapper, which is incompatible with strict CSP.

Feedback and Ideas are welcome :)

[github-actions]

Hey! Your PR title Feature/base path support 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.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

No duplicate PRs found

[github-actions]

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

1. Open an issue describing the bug/feature (if one doesn't exist)
2. Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

[PhantomYdn]

Really looking for this PR to be merged! Thank you, @hsteude. Dear maintainers - please check/merge.

[PhantomYdn]

@hsteude I was playing around with your PR. Seems that additional fix is needed. When I run from a custom base path I see the following error:

Error: Could not connect to server. Is there a server running at `http://localhost:8080`?
at l (http://localhost:8080/my/custom/base/assets/index-DT_hEdoD.js:1728:18349)

[hsteude]

@hsteude I was playing around with your PR. Seems that additional fix is needed. When I run from a custom base path I see the following error:

Error: Could not connect to server. Is there a server running at `http://localhost:8080`?
at l (http://localhost:8080/my/custom/base/assets/index-DT_hEdoD.js:1728:18349)

@PhantomYdn : Thanks for taking a look into this, good catch! I didn't realize because we tested with our own internal build where the basePath fix is baked in at build time. Added a commit that fixes the regex pattern. Also rebased on dev. Would you mind checking again if it works for you now?

[PhantomYdn]

@hsteude It partially helped, but not yet fully solve the issue. The fonts (may be other resources as well) are loaded through JavaScript and still assume hardcoded paths like /assets/. If it will help - I have patched version of base-path.ts with which everything works for me. But(!) it's solving the problem in a little bit ugly way: patching JS on the fly.
base-path.ts

[PhantomYdn]

@hsteude I have solved this problem here: https://github.com/SkyNetCMS/opencode. There are few complexities, like availablility of frontend beyond reverse proxy with fixated opencode version (apparantly "opencode web" proxy all requests to app.opencode.ai and it's posslb to have case when opencode is older and not compatible with frontend)

[DaehoYang]

Is this going to be merged?

[nick-the-nuke]

This is a high need. Making the app more compatible with reverse-proxies can help make it more secure.

[nick-the-nuke]

I get a path corruption when I use your branch, but not the SkyNet version:

[nick-the-nuke]

AI slopping together a fix right now that takes some of the changes from the SkyNetCMS repo and applies it on top of this branch

[nick-the-nuke]

@PhantomYdn thank you for your fork. AI-sloppify added your changes in prokube#3 on @hsteude's branch.

[hsteude]

@nick-the-nuke, @DaehoYang, @PhantomYdn: Since I consider this PR a) somewhat hacky myself and b) don't expect it to be merged anytime soon (and I'd rather avoid rebase hell), I've spent some time, love, and a whole lot of tokens spinning up this project: https://github.com/prokube/pk-opencode-webui

Feedback welcome!

[h0jeZvgoxFepBQ2C]

hm can this be merged? this is really blocking us from rolling out on our clusters

[PhantomYdn]

Just to be on the same page. I'm maintaining the following 2 features at https://github.com/SkyNetCMS/opencode:

1. Base Path Support - Run behind nginx at //
2. Embedded Assets - Self-hosted without external CDN

Code being true-up to current active version of opencode roughly once per week.

These fixes are needed for "aka lovable.dev" open source CMS: https://github.com/SkyNetCMS/SkyNetCMS

[Ark-kun]

@hsteude@PhantomYdn I was doing similar work and I might have found a much simpler way (just 7 lines of code) via VITE_BASE_URL. Would you mind taking a look? #18209

It does something a bit different - it bakes the prefix during the build. But this also makes it very easy to change at runtime or even via proxy. For example, you can set VITE_BASE_URL="XXX_OPENCODE_BASE_URL_XXX" and then even a transparent proxy can dynamically replace it on the fly as it serves compiled JS files. This approach can make your idea much simpler - replacing a known constant in compiled sources is simpler.

[multikoop]

This is a needed feature for broader adoption of opencode inside nowadays beeing created agentic plattforms. Would be appreciated to see this beeing merged.

[geosmart]

This is a needed feature for deploy on k8s

[geosmart]

without basic path , I use sub_filter to handle this

apiVersion: "networking.k8s.io/v1"kind: "Ingress"metadata:
name: "opencode"annotations:
nginx.ingress.kubernetes.io/ssl-redirect: "false"nginx.ingress.kubernetes.io/configuration-snippet: | rewrite ^/opencode(/|$)(.*)$ /$2 break; proxy_set_header Accept-Encoding ""; sub_filter_once off; sub_filter_types text/html application/javascript text/javascript text/css; sub_filter ' href="/' ' href="/opencode/'; sub_filter ' src="/' ' src="/opencode/'; sub_filter ' content="/' ' content="/opencode/'; sub_filter ' srcset="/' ' srcset="/opencode/'; sub_filter ' manifest="/' ' manifest="/opencode/'; sub_filter 'url(/' 'url(/opencode/'; sub_filter 'url("/' 'url("/opencode/'; sub_filter 'url:"/' 'url:"/opencode/'; sub_filter '="/assets/' '="/opencode/assets/'; sub_filter '"assets/' '"/opencode/assets/'; sub_filter '/assets/' '/opencode/assets/';labels:
app.kubernetes.io/part-of: "agent"app.kubernetes.io/component: "skill"app.kubernetes.io/instance: "opencode"spec:
ingressClassName: "nginx"rules:
- http:
paths:
- backend:
service:
name: "opencode"port:
number: 5000path: "/opencode(/|$)(.*)"pathType: "ImplementationSpecific"

[hulto]

Thank you! Need this feature to deploy in coder w/o subdomains.

[Ark-kun]

@geosmart That's not enough. The router still replaces the URL with a root-based URL. My PR provides a way to properly control taht: #18209

[carsongee]

Hi! I was really hoping we could get this in. Any updates here? I'm happy to contribute!

[PhantomYdn]

I have this built in in the following branch of opencode: https://github.com/SkyNetCMS/opencode