Skip to content

docs: reverse-proxy setup for the scene API #880

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chbndrhnns wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: reverse-proxy setup for the scene API #880

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,14 @@
# PASCAL_ADMIN_PASSWORD=change-me

# Optional bearer token for agents and scripts calling /api/scenes.
# Behind a reverse proxy, the proxy can inject this as an Authorization or
# X-Pascal-Scene-Token header.
# PASCAL_SCENE_API_TOKEN=change-me-too

# If using an upstream proxy (e.g. Cloudflare Access, Authelia, basic auth),
# set PASCAL_AUTH=proxy to allow the proxy to handle authentication.
# Ignored when PASCAL_ADMIN_PASSWORD is set.
# PASCAL_AUTH=proxy

# Allowed origins for CORS scene API requests (comma-separated).
# PASCAL_SCENE_API_ORIGINS=https://pascal.example.com
12 changes: 9 additions & 3 deletions SETUP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,9 @@ cp .env.example .env
| `PORT` | No | Dev server port (default: 3002) |
| `PASCAL_PUBLIC_URL` | No | The address people use to reach the editor. Read per request; set it when Pascal is hosted outside localhost (Mint sign-in and agent links use it). |
| `PASCAL_ADMIN_PASSWORD` | On a network host | The one password that unlocks a self-hosted editor. See "Self-hosting". |
| `PASCAL_AUTH` | No | `proxy` lets a reverse proxy that already authenticates every request replace the password. |
| `PASCAL_SCENE_API_TOKEN` | No | Bearer token for agents and scripts calling `/api/scenes`. |
| `PASCAL_AUTH` | No | `proxy` lets a reverse proxy that already authenticates every request replace the password. Ignored when `PASCAL_ADMIN_PASSWORD` is set. |
| `PASCAL_SCENE_API_TOKEN` | No | Bearer token for agents, scripts, or reverse-proxy deployments calling `/api/scenes`. |
| `PASCAL_SCENE_API_ORIGINS` | No | Comma-separated allowed origins for cross-origin scene API requests. |
| `PASCAL_DATA_DIR` | No | Directory holding `pascal.db` and artifacts (default: `~/.pascal/data`). |

Local development and the official hosted editor work without any environment variables.
Expand Down Expand Up @@ -61,7 +62,12 @@ How it is protected, by `apps/editor/lib/self-host-auth.ts`:
endpoint under "Connect an agent".
- **Fail closed.** A host that is not loopback with no password set serves a setup page
listing the variables and nothing else. `PASCAL_AUTH=proxy` opts out when a reverse proxy
(basic auth, SSO) already authenticates every request.
(basic auth, SSO) already authenticates every request; in that mode `/api/scenes` accepts
every request that reaches Pascal, so make sure the app is only reachable through the proxy.
`PASCAL_AUTH=proxy` is ignored when `PASCAL_ADMIN_PASSWORD` is set.
If you protect the scene API with `PASCAL_SCENE_API_TOKEN` behind a proxy, configure your
reverse proxy to inject `Authorization: Bearer <token>` or `X-Pascal-Scene-Token: <token>`
on forwarded requests to `/api/scenes`.
- **Loopback stays open.** `bun dev`, the CLI's managed editor and `docker run` reached at

@Aymericr Aymericr Oct 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This bullet now stops at "reached at". Please restore the two lines that were removed here:

  `localhost` need no password. Opening a dev server to another device on your LAN counts
  as a network host: set `PASCAL_ADMIN_PASSWORD` in `.env.local` for that.

`localhost` need no password. Opening a dev server to another device on your LAN counts
as a network host: set `PASCAL_ADMIN_PASSWORD` in `.env.local` for that.
Expand Down