mirror of https://github.com/getpaseo/paseo.git synced 2026-07-29 12:01:31 +00:00

Files

Matt Cowger f1a20a9fe9 Add configurable service proxy (#1280 )

* Add configurable service proxy

* Fix service proxy URL used when opening scripts with a public base URL

When a public proxy URL was configured, the View link was falling through
to direct connection logic and opening the wrong URL. Move the public URL
early-return before connection-type checks, and remove the now-dead
duplicate check further down.

* Add service proxy documentation

Covers config options, URL generation format, wildcard DNS setup,
and reverse proxy Host header requirements.

* Cap combined public service label and document hostname format

* Address service proxy review feedback

2026-06-02 14:08:41 +08:00

3.7 KiB

Raw Blame History

Service Proxy

Paseo can proxy HTTP traffic to services running inside your workspaces and expose them at stable, publicly-accessible URLs. This lets you open a running dev server from your phone or share it with a teammate without any tunneling tools.

How it works

When a paseo.json script of "type": "service" starts, Paseo assigns it a local port and registers a route in the service proxy. Incoming requests whose Host header matches the script's generated hostname are forwarded to that port.

The generated hostname is built from the script name, branch, and project:

<script>--<branch>--<project>.<base-domain>

If the branch is main or master, the branch segment is omitted:

<script>--<project>.<base-domain>

Example: a script named dev in the miniweb project on branch feature/auth would be reachable at:

dev--feature-auth--miniweb.paseoapps.my.domain.com

The public route uses one combined leftmost label (script--branch--project) rather than the local development shape (script.branch.project.localhost). This is intentional: dotted script/branch/project hostnames would require multi-level wildcard DNS and certificates for arbitrary branch names, while a single label works with normal *.base-domain DNS and wildcard TLS. If the combined label would exceed DNS's 63-character label limit, Paseo truncates it.

Configuration

Add a serviceProxy block under daemon in ~/.paseo/config.json:

{
  "version": 1,
  "daemon": {
    "serviceProxy": {
      "enabled": true,
      "listen": "0.0.0.0:8080",
      "publicBaseUrl": "https://paseoapps.my.domain.com"
    }
  }
}

Field	Required	Description
`enabled`	No	Enables the proxy. Defaults to `true` if `publicBaseUrl` is set, `false` otherwise.
`listen`	No	Address and port the proxy listens on. Defaults to `127.0.0.1:6868`.
`publicBaseUrl`	No	Base URL used to generate public service links. If omitted, links use localhost addresses only.

DNS and reverse proxy setup

For generated URLs to be reachable, you need wildcard DNS pointing to the machine running the Paseo daemon.

Example: to expose services at https://dev--miniweb.paseoapps.my.domain.com where the daemon host is 10.1.1.1:

Configure a wildcard DNS record:

*.paseoapps.my.domain.com  →  10.1.1.1

Set publicBaseUrl to https://paseoapps.my.domain.com in your config.
If you put a reverse proxy (nginx, Caddy, Traefik, etc.) in front of the daemon, ensure it forwards the Host header unchanged. The proxy uses the Host header to route requests to the correct service — rewriting it will break routing.

Nginx example:
```
server {
    listen 443 ssl;
    server_name *.paseoapps.my.domain.com;

    location / {
        proxy_pass http://10.1.1.1:8080;
        proxy_set_header Host $host;
    }
}
```

Environment variables

The listen address and public base URL can also be set via environment variables, which take precedence over config.json:

Variable	Description
`PASEO_SERVICE_PROXY_ENABLED`	`true` or `false`
`PASEO_SERVICE_PROXY_LISTEN`	Listen address, e.g. `0.0.0.0:8080`
`PASEO_SERVICE_PROXY_PUBLIC_BASE_URL`	Public base URL

3.7 KiB Raw Blame History