The Launcher

Double-click, choose GUI, Terminal, or Vellum Despana, then click Launch — with your password in the OS credential store instead of your shell history.

What it’s for

You play more than one character, and you would rather not retype an eAccess account, a game world, and a port every time. The Launcher keeps each of those as a named connection you click once. Passwords go into Windows Credential Manager, the macOS Keychain, or the Linux secret service — never into a file, never onto a command line where every process on the machine can read it. Each Launch starts a separate session process, so running four characters at once is four clicks. The Launcher is a normal native window, not a system-tray application; running the binary with no arguments opens it whenever you need it.

Set it up

The Launcher is a desktop window, so this is a frontend split: it belongs to the desktop GUI, and the terminal and mobile tabs say what you use instead.

vellum-fe --launch-profile "Nisugi hunting"

Common setups

One account, several characters, all at once

Make a connection per character, all pointing at the same Account:

1. ➕ New connection → Name Nisugi, Direct, Account MYACCT, Password once, Save password ticked, Game GemStone IV, Character Nisugi. Save.
2. ➕ New connection → Name Alt, same Account MYACCT, leave Password blank, Save password still ticked, Character Alt. Save.
3. Click Launch on both rows.

The saved password is keyed by account, not by connection, so the second one reuses the first’s stored password without you typing it again. Because each Launch spawns its own process, both characters run side by side with independent layouts.

→ Two session windows are open, each showing its own character, and the Launcher’s status line shows Launched Alt from the last click.

A connection that starts in the terminal instead

The Launcher defaults everything to the desktop GUI. To make one connection open the text interface:

1. Edit the connection.
2. Open the Advanced fold.
3. Set Frontend to Terminal.
4. While you are there, set Color mode to direct for true-color terminals, and tick Palette ▸ Set up on startup if you use slot mode on a 256-color terminal. These two rows only appear when Frontend is Terminal.
5. Save, then Launch.

→ A console window titled VellumFE opens running the terminal frontend, and it remembers its size and position the next time you launch that connection.

A connection that opens in Vellum Despana

Vellum Despana presents Vellum’s headless core and login system through a desktop browser workspace. It does not create a second login or bypass the saved connection:

1. Edit the saved connection you want to use. For Lich scripts, confirm it is a Lich connection with the expected host, detachable-client port, and character.
2. Open Advanced and set Frontend to Vellum Despana.
3. Save, then click Launch on that row.

Vellum applies the selected profile once, starts its WebUI, and opens the authoritative paired /despana URL after the server has actually bound. There is no second profile click in the browser and no token to copy. If the preferred Web dashboard port is occupied and not pinned, the server may choose a nearby port; the automatically opened URL already contains the correct port.

→ The default browser opens Vellum Despana already connecting to the saved character. The native Launcher remains available for starting another character. Closing the browser tab does not stop its independent session process: enter .exit in Despana when you mean to close it completely (.quit disconnects and returns Despana to its Launcher handoff). See Vellum Despana for workspace, map, and troubleshooting details.

Serve this session to your phone

In the connection’s Advanced fold:

1. Tick Web dashboard ▸ Enable on port and leave 8484.
2. Set Bind address to 0.0.0.0 — the hint beside it reads 0.0.0.0 = allow LAN devices. Leaving it at 127.0.0.1 restricts the server to the machine it runs on.
3. Save, Launch, then browse to http://<your-pc-ip>:8484/play on the phone.

→ The phone shows the live session, driven by the same core the desktop window is rendering.

Tips & gotchas

⚠️ The Launcher defaults to the GUI; a hand-typed command line defaults to the TUI. A new connection is created with Frontend: GUI, but vellum-fe invoked with flags uses --frontend tui unless you say otherwise. The same character launched two ways can land in different interfaces. Set GUI, Terminal, or Vellum Despana explicitly under Advanced ▸ Frontend. The CLI’s --frontend headless runs a browser-only session directly; selecting Vellum Despana in the Launcher is the convenient saved-connection path to that desktop presentation.

⚠️ Deleting a connection can delete the saved password with it. The confirmation window Delete profile? says so: the keyring entry is removed unless another connection still uses the same account. Deleting your only MYACCT connection means the next one has to re-enter the password.

• “Password was NOT stored” in red means the credential store refused the write — common on headless Linux, inside WSL, or under a bare window manager with no secret service running. The connection still saves and still launches; you are asked for the password each time. Install a secret service (GNOME Keyring, KWallet) to fix it.
• A red line about launcher.toml on startup means the file could not be parsed. The Launcher deliberately shows the error rather than starting with an empty list, because saving from an empty list would overwrite your connections. Fix the file before saving anything.
• Connection names cannot contain " or %. The Launcher rejects them at save time, because a terminal session’s name travels through a Windows cmd command line where neither can be passed safely.
• Renaming a connection does not duplicate it. The edit form tracks the name you started with and replaces that entry.
• The account name is not shown in the list. Each row’s summary is <character> @ <game> on purpose — the list is on screen constantly, and in screenshots. The account stays inside the edit form.
• Nothing in the list? “No saved connections yet” with Create one to get started is the empty state, not an error.

The other launcher: cold-starting Lich over SSH

There is a second, separate feature with a confusingly similar name. The SSH Launcher does not manage connections — it starts a headless Lich on your home PC from wherever you are, over an existing WireGuard or Tailscale tunnel, then attaches to it. Use it when the machine that runs Lich is not the machine you are sitting at.

It lives inside a running session, not in the Launcher window:

• Type .launcher (or bare .launch) in the command input to open the SSH Launcher panel.
• Fill in Host (tunnel address), User, SSH port, Remote OS, optionally Attach host, and the Launch command template — where {character}, {game} and {port} are substituted per character.
• Click Generate new key, then Copy public key and paste that one line into ~/.ssh/authorized_keys on the home PC. The private half goes to your OS secure store; the indicator changes to ✓ key stored. Expand Harden it (recommended) to see the restrict,command="…" prefix that limits a leaked key to launching the game and nothing else.
• Add each character under Characters with its game token and its own detachable-client Port, then Save.
• Run it with .launch <character>.

If a Lich is already listening on that port, the flow skips the SSH step entirely and attaches straight away. If not, it SSHes in, spawns Lich detached so it survives the SSH channel closing, then polls the port. The open port — not the spawn’s exit code — is what counts as success, so a message like “Launched Lich but 100.64.0.5:8001 never opened” means the command template or the character name is wrong, and the spawner’s own output is appended to tell you which. On a first connection the host key’s fingerprint is pinned; if a pinned key ever changes, the launch is refused outright rather than prompting.

→ .launch Nisugi reports progress in the session and ends attached to the freshly started Lich.

See also

• Installing VellumFE — getting the binary in the first place
• First Launch — connecting with flags instead of connections
• Desktop GUI · Terminal (TUI) · Vellum Despana
• Put VellumFE on your phone — the web dashboard