Server options

This page lists the termul-server settings you are most likely to change. Run termul-server --help for the full list.

Main flags

When you set both a flag and its environment variable, the flag wins.

The state folder is $XDG_STATE_HOME/termul when XDG_STATE_HOME is set. Otherwise it is ~/.local/state/termul.

To see more detail in the logs, start the server with RUST_LOG=termul_manager_lib=debug.

The access token

The access token is a password for the server. A browser must have it before it can use Termul.

• On 127.0.0.1, there is no token unless you set one with --web-auth-token.
• On 0.0.0.0, a token is always required. If you didn't set one, the server creates a random token the first time it starts. It saves the token in <state dir>/web-auth-token, readable only by your user. The server never prints the token or writes it to the logs. Later starts reuse the same token.

To read the generated token:

cat ~/.local/state/termul/web-auth-token

To open Termul with the token, add it to the address after #token=:

http://<server-address>:8080/#token=<token>

The part after # stays in your browser and is not sent to the server as part of the address. The browser saves the token, removes it from the address bar, and uses it on later visits. If you open the server without the token, Termul asks for it. See Enter the token.

To change the token, stop the server, delete the web-auth-token file, and start the server again. Every browser then has to enter the new token.

Treat the token like an SSH private key. Anyone who has it can read any file the server's user can read. With remote changes allowed, they can also run commands as that user.

Prefer the file or the TERMUL_WEB_AUTH_TOKEN variable over --web-auth-token. Other users on the machine can see a flag's value in the process list.

Allow changes from other devices

By default, a browser on another device is view-only. It can watch chats and terminals, and read files and git history. It can't do any of these:

• Send prompts, stop agents, or answer approvals and questions.
• Open, type into, or close terminals.
• Create, edit, rename or delete files.
• Stage, commit, or change branches and worktrees.
• Add or remove projects.

A browser on the same machine as the server can always make changes. So can a reverse proxy that runs on the same machine and connects to 127.0.0.1.

To let other devices make changes, start the server with --allow-remote-writes:

termul-server --host 0.0.0.0 --allow-remote-writes

With this flag, other devices can do everything. File changes from other devices stay inside your registered projects. The token is still required.

The default is view-only because changes from another device run with your user's permissions on the server. Turn the flag on only when you trust the network, or when the server is behind HTTPS. The flag has no effect when the server listens on 127.0.0.1.

Put a reverse proxy in front

A reverse proxy such as Caddy or nginx can add HTTPS in front of Termul. HTTPS keeps the token private on the network. It also lets phones install Termul as an app and show notifications.

1. Start the server on 127.0.0.1, for example termul-server --host 127.0.0.1 --port 8080.
2. Point the proxy at 127.0.0.1:8080. Turn on WebSocket support in the proxy. Termul keeps a live connection open to the browser, and WebSocket is the kind of connection it uses.

With Caddy, this is the whole configuration:

termul.example.com {
	reverse_proxy 127.0.0.1:8080
}

The server checks that browser requests come from its own address. A proxy that passes the public host name through, as Caddy does by default, needs nothing more. If your proxy changes the host name to the upstream address, the browser gets refused. List the public address with --allowed-origins:

termul-server --host 127.0.0.1 --port 8080 --allowed-origins https://termul.example.com

Update the server

The server can update itself from the GitHub releases. Each download is checked against a signature before the server uses it. Builds you compile yourself can't self-update.

There are three update channels:

• stable: tested releases.
• insider: releases before they reach stable.
• nightly: a new build each night.

To update once, run:

termul-server --check-update

This uses the channel in TERMUL_SERVER_UPDATE_CHANNEL, or stable if that isn't set. It replaces the program file and keeps the old one next to it as termul-server.old. Restart the server to run the new version.

To check for updates in the background, set these environment variables before you start the server:

When the server finds a new version in the background, it installs it and restarts itself. The setup wizard sets these variables for you when you pick an update channel.

Docker images don't update themselves. Pull a new image instead. See Install the server.