Service and storage

Updated on November 10, 2026

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 konsolity system user, without a shell or a password;
  • installs the konsolity.service unit 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 /home from the service);
  • installs the konsolity-update.timer timer, 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.