Service and storage
konsolity serve handles the requests of the account's Claude connector like the desktop app would, but without an interface: Claude can act on your servers even when your computer is off, within the scope and rules of the machine. It requires the mcp domain and the Claude integration of the Studio plan, and the Claude connector must already be added in Claude.
Try it in the foreground
konsolity serve
The command stays in the foreground and shows every request handled or refused. Ctrl+C stops it. For a real server, install it as a service.
Linux: systemd
sudo konsolity service install
The command:
- creates the
konsolitysystem user, without a shell or a password; - installs the
konsolity.serviceunit with automatic restart (Restart=always) and the systemd sandbox (ProtectSystem=strict,NoNewPrivileges=yes); - stores the configuration in
/etc/konsolity/and the state in/var/lib/konsolity/; - encrypts the secrets with
systemd-creds(see below); - copies the binary to
/usr/local/bin/konsolity(the sandbox hides/homefrom the service); - installs the
konsolity-update.timertimer, which checks the signed release twice a day, updates the binary and restarts the service; - enables and starts the service.
The service starts with the system and restarts on its own after an error or a network outage. Its logs:
journalctl -u konsolity
journalctl -u konsolity -f
Several servers: main relay and backup
Activate Konsolity CLI on two or more servers, each with service install. One relay handles each Claude request: the one with the highest priority (Settings › Claude › Claude relays). The others stand by, with no app or Mac running.
If the main relay stops cleanly, the next one takes over within a second. If it goes down without warning, the next one takes a request left unanswered after 6 seconds, the third one after 12 seconds. A request never runs twice. The journal shows the role of each machine: "Active relay" or "Standby".
For a backup relay to take over commands too, its rules must allow commands (Settings › CLI machines › the machine › Rules). Otherwise it only takes over reads (hosts, snippets, sessions).
macOS: launchd
sudo konsolity service install
Installs the com.konsolity.cli launchd service, restarted automatically (KeepAlive). The secrets are stored in the keychain. The logs are in the Console app.
Windows: scheduled task
In an administrator PowerShell:
konsolity service install
Creates a scheduled task that starts konsolity serve when Windows starts and restarts it after an error.
Check
konsolity status
status tells whether the machine is reachable, the age of the token, the scope and the number of reachable hosts. The machine shows as online in the CLI machines list as long as it gave a sign of life in the last minute.
Folders
| Path | Content |
|---|---|
~/.config/konsolity/ |
Linux and macOS, use without a service: config.json and secrets |
%APPDATA%\Konsolity\cli\ |
Windows: config.json and credentials.bin |
/etc/konsolity/ |
Linux service: configuration |
/var/lib/konsolity/ |
Linux service: encrypted secrets and state |
config.json (server address, identifier and name of the machine, displayed scope) is 0600. It contains no secret.
Secret storage
The secrets of the machine are its token and its machine key. They are stored according to the system:
| System | Storage |
|---|---|
| macOS | Keychain (item com.konsolity.cli) |
| Linux, as a service | systemd-creds encrypt, with the TPM when the machine has one, otherwise with the host key |
Linux, without systemd-creds |
credentials.bin file, 0600 |
| Windows | DPAPI (current user) in credentials.bin, access restricted to the account alone |
In every case, the content is first encrypted with a key derived from the machine identifier: copied to another computer, it is unreadable. Secrets never appear in a log, a command line argument or an environment variable, except KONSOLITY_TOKEN which you choose to provide for a long-lived token.
Automatic token rotation
The token of a machine is renewed automatically every 24 hours, without interruption: the old token stays accepted until the first call made with the new one, 10 minutes at most. To force a rotation (after restoring a backup, after a third party worked on the machine):
konsolity rotate
Long-lived tokens (setup-token) have no automatic rotation; they expire after one year at the latest.
Remove the service
sudo konsolity service uninstall
The service is stopped and removed. The machine stays activated on your account: to cut it off too, run konsolity logout or revoke it from the CLI machines list.