WeTTY can be run with the --help flag to get a full list of flags.
WeTTY runs on port 3000 by default. You can change the default port by
starting with the --port or -p flag.
By default WeTTY listens on 0.0.0.0 (all interfaces). You can change this with
the --host flag, for example --host 127.0.0.1 to only listen on localhost.
Instead of listening on a TCP port, WeTTY can listen on a unix socket using the
--socket flag. This is mutually exclusive with --host and --port.
If WeTTY is run as root while the host is set as the local machine it will use
the login binary rather than ssh. If no host is specified it will use
localhost as the ssh host.
If instead you wish to connect to a remote host you can specify the host with
the --ssh-host flag and pass the IP or DNS address of the host you want to
connect to.
You can specify the default user used to ssh to a host using the --ssh-user.
This user can overwritten by going to http://yourserver:3000/ssh/<username>.
If this is left blank a user will be prompted to enter their username when they
connect.
By default WeTTY will try to ssh to port 22, if your host uses an alternative
ssh port this can be specified with the flag --ssh-port.
If you’d prefer an HTTP base prefix other than /, you can specify that with
--base.
Do not set this to /ssh/${something}, as this will break username matching
code.
Configure every trusted browser origin explicitly with --allowed-origin,
ALLOWEDORIGINS, or server.allowedOrigins in the config file. WeTTY refuses
to start without at least one origin, including for local development.
wetty --allowed-origin http://localhost:3000
# Behind an HTTPS reverse proxy:
wetty --allowed-origin https://terminal.example.com
Repeat the flag to allow multiple origins. The ALLOWEDORIGINS environment
variable accepts a comma-separated list. Each entry must be a complete HTTP(S)
origin (scheme, hostname and optional port), without credentials, paths, query
strings, fragments or wildcards. The base path is not part of the origin.
Only configured origins are trusted. Matching request Host and Origin
headers does not grant access, and forwarded headers never add trusted origins.
Reverse proxies should preserve the browser-facing Host header. A browser may
omit Origin on same-origin polling requests; these require both
Sec-Fetch-Site: same-origin and a Host matching a configured origin’s host and
port. Rewriting Host to an internal backend name will prevent this
missing-Origin polling fallback from working.
Non-browser clients such as CLI tools and scripts may not send an Origin
header or browser Fetch Metadata. By default WeTTY rejects these requests.
To allow them, use --allow-missing-origin:
wetty --allowed-origin http://localhost:3000 --allow-missing-origin
The ALLOWMISSINGORIGIN=true environment variable has the same effect.
Warning: This opt-in bypasses origin protection for requests that omit
Origin, including the missing-Origin DNS-rebinding defense. Use it only behind an independently authenticated, host-validating proxy. An explicit origin allowlist is still required at startup. Supplied untrusted, malformed ornullorigins remain rejected.
By default WeTTY does not allow the host and port URL parameters to be used
as the SSH destination. To enable this, use the --allow-remote-hosts flag.
By default WeTTY does not allow the command and path URL parameters to
specify the command and working directory on the SSH host. To enable this, use
the --allow-remote-command flag.
WeTTY’s browser terminal rides on a Socket.IO connection, kept alive with a
heartbeat: the server pings the client every --ping-interval milliseconds
(default 3000) and expects a pong back within --ping-timeout milliseconds
(default 7000), or it closes the transport (shown to the user as a “transport
close” error requiring reconnect).
These defaults are tight compared to Socket.IO’s own defaults (25000/20000). On
a high-latency or lossy network path, a single delayed pong can exceed the 7
second timeout and force a reconnect even though the underlying connection is
otherwise healthy. If you see frequent “transport close” errors, try raising
both, e.g. --ping-interval 25000 --ping-timeout 20000.
Both flags also accept the PINGINTERVAL and PINGTIMEOUT environment
variables.
The unauthenticated metrics endpoint is ${base}/metrics (/metrics with the
default base). Restrict access at your reverse proxy if it exposes operational
data you do not want to make public.
HTTP metrics use five fixed route families: the terminal page, /ssh/:user,
/client/*, /sw.js, and unmatched, prefixed by the configured base where
applicable. Usernames, asset names, unknown paths and query strings are never
retained as labels. Methods use the seven common HTTP methods or OTHER, and
statuses are grouped into 2XX, 3XX, 4XX, or 5XX. Scrapes are not
counted.
You can set the log level of the WeTTY server using the --log-level flag.
Accepts standard log levels (e.g. debug, http, info, warn, error).