kovidgoyal/kitty · error · SystemExit

Password usage requested but KITTY_PUBLIC_KEY environment va

Error message

Password usage requested but KITTY_PUBLIC_KEY environment variable is not available

What it means

Encrypted remote control requires kitty's public key exported as KITTY_PUBLIC_KEY (set by kitty when launching a kitten so it can decrypt). If empty, SystemExit is raised.

Source

Thrown at kitty/remote_control.py:525

        else:
            try:
                with open(resolve_custom_file(opts.password_file)) as f:
                    ans = f.read().rstrip()
            except OSError:
                pass
    if not ans and opts.password_env:
        ans = os.environ.get(opts.password_env, '')
    if not ans and opts.use_password == 'always':
        raise SystemExit('No password was found')
    if ans and len(ans) > 1024:
        raise SystemExit('Specified password is too long')
    return ans


def get_pubkey() -> tuple[str, bytes]:
    raw = os.environ.get('KITTY_PUBLIC_KEY', '')
    if not raw:
        raise SystemExit('Password usage requested but KITTY_PUBLIC_KEY environment variable is not available')
    version, pubkey = raw.split(':', 1)
    if version != RC_ENCRYPTION_PROTOCOL_VERSION:
        raise SystemExit('KITTY_PUBLIC_KEY has unknown version, if you are running on a remote system, update kitty on this system')
    from base64 import b85decode

    return version, b85decode(pubkey)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Run the command via kitten (which kitty launches with KITTY_PUBLIC_KEY set)
2. Over SSH, forward the variable or source it: export KITTY_PUBLIC_KEY=$(kitten @get-public-key 2>/dev/null || echo "$KITTY_PUBLIC_KEY")
3. Avoid --use-password on the remote side if env cannot be provisioned

Example fix

# ssh config host block
SendEnv KITTY_PUBLIC_KEY
# sshd: AcceptEnv KITTY_PUBLIC_KEY

import os
assert os.environ.get('KITTY_PUBLIC_KEY'), 'run this via kitten or forward KITTY_PUBLIC_KEY'

def has_pubkey_env() -> bool: return bool(os.environ.get('KITTY_PUBLIC_KEY'))

When it happens

Trigger: Invoking remote-control with password/encryption from a process where KITTY_PUBLIC_KEY is not in the environment — e.g. a shell script run outside kitten, or over SSH where the variable was not forwarded.

Common situations: Running @ commands via ssh without SendEnv/forwarding, or from cron/scripts where the env var is missing.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Invalid KITTY_LISTEN_ON: %#v
• This should be run as kitten icat
• This should be run as `kitten notify ...`
• Remote control not enabled, this kitten should be run via a
• The remote control password was invalid: {data!r}

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/275c65b686a2e3e4. Report an issue: GitHub.