Commands and settings
Reference for both programs: commands, options, files and ports.
humble (the desktop app)
| Command | What it does |
|---|---|
humble | Open the app. |
humble connect <target> [--password <pw>] [--fullscreen] | Open the app and connect to an address or a 9-digit ID. Without --password you are asked for it. The password can also come from HUMBLE_PASSWORD. --fullscreen opens the session in full screen. |
humble status | Show the running host's name, ID, one-time password, server state and sessions. |
humble set-password [<pw>] | Set the permanent password. Without a value, remove it. |
humble install [--enroll <code>] | Set up the background service and, optionally, enroll into a server. |
humble uninstall | Remove the background service. |
humble enroll <code> | Enroll this computer into a server using a code from the Deploy page. |
humble login <server> <username> --password <pw> [--totp <code>] [--trust-certificate <fingerprint>] | Sign in to a server, as on the Computers page. The password can come from HUMBLE_LOGIN_PASSWORD. A server with a self-signed certificate is refused with its fingerprint; check it against the server's and pass it with --trust-certificate. |
humble add-this-computer [--group <id>] | Add this computer to the account you signed in to (needs an admin of it), as Add this computer does. |
humble host --headless [--no-control-port] | Run only the host part, with no window. This is what the background service runs. --no-control-port lets it run next to another Humble. |
humble --tray | Start with only the tray icon (used at sign-in when the background service is installed). |
humble service install | uninstall | Register or remove the background service without the other steps of install. |
humble terminal <target> [--password <pw>] | Open a terminal session on a computer running the headless service, in this terminal (like ssh). By 9-digit ID (signed in) or address. |
sudo humble headless setup [--user <name>] [--mode terminal|console] [--allow-root] | Turn on the Linux headless service: a remote terminal as that account (default), or the text console. |
sudo humble headless remove | Stop and disable the headless service (its identity is kept). |
humble headless run [--mode terminal|console] | Run the headless service (what its systemd unit starts). |
humble humble://connect?server=…&device=… | Open a link from the dashboard. The system does this for you when you press Connect in the browser. |
Options for every command
| Option | Environment variable | Meaning |
|---|---|---|
--config-dir <folder> | HUMBLE_CONFIG_DIR | Use another settings folder. |
--headless-service | Act on the Linux headless service instead of the desktop app's host (status, set-password, login, add-this-computer, enroll): its settings in /var/lib/humble-headless and its control port. Use it as the account the service runs as, or as root. | |
--log-file <file> | Write logs to this file only. Without it, the app window also keeps a log file; see Getting more detail. | |
--debug | Log Humble's debug detail on the console too. | |
RUST_LOG | Log detail, for example debug. Overrides --debug. | |
HUMBLE_CAPTURE=poll | Use the screenshot-based capture. Try this if the screen stays black. It is already the default on Hyprland and sway. | |
HUMBLE_CAPTURE=portal | Use the desktop's screen-sharing dialog even on GNOME, Hyprland and sway, which need no dialog otherwise. |
humble-support
| Command | What it does |
|---|---|
humble-support | Open Humble Support. |
humble-support --share | Start sharing this computer right away ("My computer is being connected to"). |
humble-support --connect <ID> | Connect to an ID right away ("I am connecting to another computer"). |
humble-support --relay <url> | Use another relay than the public one (also HUMBLE_RELAY). |
humble-server
| Command | What it does |
|---|---|
humble-server serve [options] | Run in the foreground. This is the default when no command is given. |
humble-server service install [options] | Install and start the background service with these options. |
humble-server service uninstall | Stop and remove the service. Data is kept. |
humble-server create-admin <name> --password <pw> | Create an administrator. |
humble-server reset-password <name> --password <pw> | Set a new password and turn off that user's two-factor sign-in. |
humble-server public-key | Print the server's public key. |
The options are listed under Set up the server. Commands that read or change accounts must use the same
data folder as the running service. They do so by default when run as Administrator or with sudo; otherwise pass --data.
Where things are stored
| What | Windows | Linux | macOS |
|---|---|---|---|
| App settings and keys | %APPDATA%\Humble\Humble\config | ~/.config/humble | ~/Library/Application Support/com.Humble.Humble |
| Background service settings | C:\ProgramData\Humble | Same as the app | Same as the app |
| Server data | C:\ProgramData\HumbleServer | /var/lib/humble | /Library/Application Support/HumbleServer |
The exact settings folder is shown at the bottom of the app's Settings page. Settings are in config.json. It contains this
computer's private keys, so do not share it. Deleting it gives the computer a new identity.
Network ports
| Port | Used by | Direction | Purpose |
|---|---|---|---|
| TCP 21420 | App | Incoming on the controlled computer | Direct connections. Change it in Settings. |
| UDP 5353 | App | Local network | Finding nearby computers (mDNS). |
| TCP 21421 | App | This computer only | Lets the window and humble status talk to the background service. |
| TCP 21422 | Headless service (Linux) | Incoming on the computer | Direct connections to the terminal or console. |
| TCP 21423 | Headless service (Linux) | This computer only | Lets humble --headless-service … talk to it. |
| TCP 8080, or what you set | Server | Incoming on the server | Dashboard, device connections and relayed sessions. Usually 443 with HTTPS. |
Computers that use a server only make outgoing connections to it, so they need no open ports and no router changes.