Environment and configuration

Precedence

Flags beat environment variables, which beat a template, which beats the built-in default.

Variables

Variable	Equivalent flag	Description
`PORTHOLE_SERVER`	`--server`	Signaling server URL.
`PORTHOLE_LOG_LEVEL`	`--log-level`	`debug`, `info`, `warn`, or `error`.
`PORTHOLE_SHELL`	`--shell`	Shell to spawn for a hosted session.
`PORTHOLE_PASSWORD`	`--password`	Session password. Prefer this over the flag — see below.
`PORTHOLE_RECORD_OUTPUT`	`--record-output`	Where to write a recording.
`PORTHOLE_TITLE`	`--title`	Title stored in a recording's header.
`PORTHOLE_ALLOW_ROOT`	`--allow-root`	Accepts `1`, `true`, `yes`, or `on`.
`PORTHOLE_CONFIG_DIR`	—	Override the configuration directory. Must be absolute.

Why PORTHOLE_PASSWORD is the recommended form

A command line is world-readable in ps on most systems and lands in your shell history. An environment variable avoids both. --password exists for scripts that are already handling the value carefully.

Configuration directory

Where templates live. Print the resolved path with porthole template path.

Resolution order:

PORTHOLE_CONFIG_DIR, if set. Must be an absolute path.
~/.porthole, if it already exists — so an install that predates the current layout keeps working.
On Linux and BSD: $XDG_CONFIG_HOME/porthole, else ~/.config/porthole.
On macOS: ~/Library/Application Support/porthole.
On Windows: %AppData%\porthole.

Running as root

porthole host refuses to run as root.

porthole host --allow-root          # the only way past it
PORTHOLE_ALLOW_ROOT=1 porthole host # equivalent

This is enforced rather than advised, because sharing a root shell hands whoever holds the link full control of the machine — and unlike most "do not run as root" warnings, here the privileges are being handed to a remote party.

Almost everything people reach for sudo for can be done from an unprivileged shell with sudo used per-command inside the session, which also means each privileged action is visible in the shared scrollback rather than implicit in the whole session.

--allow-root is deliberately not settable from a template. Bypassing the refusal should be a decision you make at the command line in the moment, not one a saved file makes for you.

Build-time defaults

The agent's default server and update URLs are injected at build time, so no production URL is committed to source. A binary you build yourself points at ws://localhost:8080/ws unless you set them:

go build -ldflags "\
  -X github.com/ProfessorHusnain/porthole/agent/internal/defaults.ServerURL=wss://signal.example.com/ws \
  -X github.com/ProfessorHusnain/porthole/agent/internal/defaults.UpdateURL=https://example.com/version.json"

An empty UpdateURL disables the background update check entirely.

Viewer

The browser viewer reads one variable at build time:

Variable	Description
`VITE_SIGNALING_URL`	WebSocket URL of the signaling server.