Running the Self Hostd launcher from the command line
The full command-line reference for the Self Hostd launcher: every flag, the selfhostd.properties file, token handling, modes and exit codes.
The short version
The Self Hostd launcher runs from the command line with a 6-digit pairing code on first run and a stored token afterwards. It supports several modes, a set of flags, and a selfhostd.properties file for persistent configuration. Exit codes tell you whether a failure was pairing, network or configuration.
The launcher runs fully from a terminal, which suits headless boxes, scripts and anyone who does not want the graphical window. Everything the window does with buttons, the command line does with flags and one settings file.
#First run
From your server folder:
java -jar selfhostd-launcher.jar --pair-code 123456 -- java -Xmx4G -jar server.jar nogui
Everything after -- is your server's own start command; the launcher starts it, tunnels players to it and relays its console to your panel. Pairing exchanges the 6-digit code for a token and saves it to selfhostd.properties in the working directory.
#Every run after that
Run the same command again, or drop the options entirely:
java -jar selfhostd-launcher.jar -- java -Xmx4G -jar server.jar nogui
A leftover --pair-code is ignored once a token is saved, so a start script never needs editing. The properties file is shared with the graphical launcher: pair in the window, run from the terminal later, or the other way round.
#Modes
| You run | You get |
|---|---|
... -- <server command> | Launcher starts and supervises your server, plus tunnel and panel link |
no -- part | Tunnel-only: expects a server already listening on the local port |
--no-tunnel -- <server command> | Your server and the panel link, no Hostd tunnel (details) |
#Flags
| Flag | What it does |
|---|---|
--pair-code <code> | 6-digit code from your panel; exchanged for a token on first run, ignored once paired |
--local-port <port> | Port your server listens on, where the tunnel delivers players (default 25565) |
--local-host <host> | Address the tunnel delivers players to (default 127.0.0.1; a container name in Docker setups) |
--no-tunnel | Keep the panel link but skip the Hostd tunnel |
--token-file <path> | Read the token from a file instead of the properties file |
--relay <host:port> | Override the relay address (normally set automatically at pairing) |
--api <url> | Override the control-plane URL (only useful in development) |
--insecure | Skip TLS verification (development only, never in normal use) |
--gui | On its own (no other flags), opens the graphical window |
--help | Print the usage summary |
#Where the token comes from
The launcher looks for the token in this order and uses the first one it finds:
--token-file <path>- the
SELFHOSTD_TOKENenvironment variable selfhostd.propertiesin the working directory
It is never accepted as a command-line argument, so it cannot leak into shell history or process lists. For containers and scripts, the environment variable is usually the right choice.
#selfhostd.properties
Flags beat environment variables, which beat the file. The two on-switches, --no-tunnel and --insecure, only switch on; to turn either back off, remove its line from the file. The keys the command line reads:
| Key | Meaning |
|---|---|
token | Saved at pairing; delete this line (and unset SELFHOSTD_TOKEN) to pair afresh |
relay | Relay address, saved at pairing |
localPort | Same as --local-port |
localHost | Same as --local-host |
tunnel | Set false for the same effect as --no-tunnel |
api, insecure | Development overrides |
The graphical launcher stores its own settings (server jar, RAM, restart behaviour) in the same file; the command line leaves those untouched.
#What the panel can do in terminal mode
When the launcher supervises your server (you gave it a start command after --), console commands sent from the web panel reach the server and the panel's stop button stops it. In tunnel-only mode there is no attached server, so console commands are dropped, and the panel's stop button stands the tunnel down instead; restart the launcher to bring it back. Restart, backups and restores need the graphical launcher in either mode; asking for one from the panel leaves it queued until a graphical launcher connects.
#Messages and exit codes
The launcher prints panel link up when the panel connection is healthy and panel link down while it retries. If the server is removed in your panel or the token stops being accepted, it explains what happened, clears the saved token and, when it has nothing left to do, exits.
| Exit code | Meaning |
|---|---|
| 2 | Bad flags or no token found |
| 3 | Disconnected by the panel (server removed, or token no longer accepted) |
| anything else | Your server's own exit code, passed through |
#Frequently asked questions
Where does the Self Hostd launcher store its token?
In selfhostd.properties next to the launcher, written after the first successful pairing. Treat that file as a credential: anyone with it can act as your server's launcher.
Can I run Self Hostd without a terminal attached?
Yes. The launcher has modes for running unattended, and the panel keeps its console link either way. What the panel can do varies by mode, which the modes section of this article covers.
What do the Self Hostd exit codes mean?
They separate pairing failures from network failures from configuration problems, so an automated restart wrapper can tell the difference between something worth retrying and something that needs you.
Written and maintained by the Hostd engineering team. Last updated 2026-08-02. Notice a mistake? Tell us.