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).