kovidgoyal/kitty · error · ValueError

Remote control not enabled, this kitten should be run via a

Error message

Remote control not enabled, this kitten should be run via a map in kitty.conf, not from the command line

What it means

Raised when a kitten TUI handler runs outside kitty (running_in_kitty() is False) with allow_remote_control=True, but the KITTY_LISTEN_ON environment variable is unset. Without a listen socket the kitten cannot send remote control commands back to a parent kitty instance, which is the only supported way to launch such kittens from the command line.

Source

Thrown at kittens/tui/handler.py:75

    def __init__(self, func: Callable[[list[str]], str], allow_remote_control: bool, remote_control_password: bool | str):
        self.func = func
        self.allow_remote_control = allow_remote_control
        self.remote_control_password = remote_control_password
        self.password = self.to = ''
        self.rc_fd = -1
        self.initialized = False

    def initialize(self) -> None:
        if self.initialized:
            return
        self.initialized = True
        if running_in_kitty():
            return
        if self.allow_remote_control:
            self.to = os.environ.get('KITTY_LISTEN_ON', '')
            if not self.to:
                raise ValueError('Remote control not enabled, this kitten should be run via a map in kitty.conf, not from the command line')
            self.rc_fd = int(self.to.partition(':')[-1])
            os.set_inheritable(self.rc_fd, False)
        if (self.remote_control_password or self.remote_control_password == '') and not self.password:
            import socket

            with socket.fromfd(self.rc_fd, socket.AF_UNIX, socket.SOCK_STREAM) as s:
                data = s.recv(256)
            if not data.endswith(b'\n'):
                raise Exception(f'The remote control password was invalid: {data!r}')
            self.password = data.strip().decode()

    def __call__(self, args: list[str]) -> str:
        self.initialize()
        return self.func(args)

    def allow_indiscriminate_remote_control(self, enable: bool = True) -> None:
        if self.rc_fd > -1:
            if enable:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Run the kitten via a map in kitty.conf (e.g. map f1 launch --type=overlay kitten_name) so kitty provides the socket
2. Or start kitty with listen_on set (kitty --listen-on unix:/tmp/kitty) and export KITTY_LISTEN_ON for the child
3. For non-interactive testing, set allow_remote_control=False and stub out remote_control calls

Example fix

# before
handler = ResultHandler(func, allow_remote_control=True)  # fails outside kitty
# after
# add to kitty.conf:  map f1 launch --type=overlay mykitten
# and launch with the map so KITTY_LISTEN_ON is inherited

import os
from kittens.tui.handler import running_in_kitty
def can_use_remote_control() -> bool:
    return running_in_kitty() or bool(os.environ.get('KITTY_LISTEN_ON'))

def is_launchable_in_kitty(env: dict[str, str]) -> bool:
    return 'KITTY_LISTEN_ON' in env or 'KITTY_WINDOW_ID' in env

try:
    handler.initialize()
except ValueError as e:
    if 'Remote control not enabled' in str(e):
        sys.exit('Run this kitten via a map in kitty.conf')
    raise

When it happens

Trigger: Running a kitten directly from a plain shell (not via a kitty map or kitten CLI inside kitty) with allow_remote_control=True and no KITTY_LISTEN_ON in the environment; e.g. python -m some_kitten outside a kitty window.

Common situations: Testing a kitten in a normal terminal or over SSH; running kitten scripts under cron/CI; kitty.conf missing the map that launches the kitten; kitty started without --listen-on / listen_on config.

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

• Remote control is not enabled, remember to use allow_remote_
• Password usage requested but KITTY_PUBLIC_KEY environment va
• KITTY_PUBLIC_KEY environment variable does not have a : in i
• This should be run as kitten icat
• This should be run as `kitten notify ...`

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