Remote Control Basics
Kitty exposes a remote control protocol that lets you send commands to a running kitty instance from the shell, scripts, or other programs. This is the foundation for automating terminal workflows.
Remote control allows you to script window/tab creation, change themes on the fly, and integrate kitty with automation tools. Start with the basics — kitty @ ls and kitty @ launch — then build up.
Remote Control Architecture
┌─────────────────────────────────────────────────────┐
│ Remote Control Flow │
│ │
│ Shell / Script / Cron │
│ │ │
│ ▼ │
│ kitty @ <command> │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ Kitty Unix Socket │ │
│ │ (/tmp/kitty-XXXX/socket-1) │ │
│ └──────────┬───────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ Kitty Server (background) │ │
│ │ - Parses JSON commands │ │
│ │ - Executes action │ │
│ │ - Returns response │ │
│ └──────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ OS Window(s) Updated │ │
│ │ - New window opened │ │
│ │ - Theme changed │ │
│ │ - Tab focused, etc. │ │
│ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
Enabling Remote Control
Remote control is disabled by default for security. Enable it in kitty.conf:
# Security levels:
# y — enabled (no password)
# password — enabled with password
# n — disabled (default)
# socket-only — only via socket, not from inside kitty
# socket — alias for socket-only
allow_remote_control y
Setting allow_remote_control y allows any process running as your user to control kitty. On multi-user systems or shared development environments, use password or socket-only instead.
Password-Protected Remote Control
# Enable with password
allow_remote_control password
# Store password in kitty's keychain
kitty @ set-password
# (enter your password when prompted)
When password is set, all kitty @ commands require --password:
kitty @ --password "mypassword" ls
Socket-Only Mode
socket-only restricts remote control to connections over the Unix socket only — commands typed inside kitty itself won't work:
# Most secure: only remote socket access
allow_remote_control socket-only
The Kitty Shell (kitty +kitten shell)
The shell kitten provides interactive access to remote control:
# Enter the remote control shell
kitty +kitten shell
# Now type commands interactively
> launch --type=window --cwd /etc
> set-font-size 14
> set-colors --configured ~/my-theme.conf
> exit
Communication via Socket
Kitty listens on a Unix socket located at:
/tmp/kitty-<PPID>/socket-<number>
Find the active socket:
# Show kitty instance info including socket path
kitty @ ls
# Or find sockets manually
ls /tmp/kitty-*/
# Connect to the socket directly (for debugging)
echo '{"cmd":"ls"}' | nc -U /tmp/kitty-12345/socket-1
Each running kitty instance has its own socket. If you launch multiple kitty OS windows independently, kitty @ targets the first one in the list. Use kitty @ --to <socket> to target a specific instance.
Enabled Remote Control Permissions
| Permission Level | Description | Use Case |
|---|---|---|
n | Disabled | Production / security-sensitive |
y | Full access without password | Personal workstation, single user |
password | Full access with password | Shared workstation, SSH-forwarded |
socket-only | Only via socket, not from inside kitty | Defense-in-depth |
socket | Alias for socket-only | — |
Basic Remote Control Commands
# List kitty instance info
kitty @ ls
# Open a new window with a specific command
kitty @ launch --type=window --cwd /var/log --title "Logs" tail -f syslog
# Open a new tab
kitty @ launch --type=tab
# Change colors on the fly
kitty @ set-colors --configured ~/.config/kitty/colors.conf
# Set font size
kitty @ set-font-size 14
# Close the focused window
kitty @ close-window
# Focus a specific window
kitty @ focus-window --match title:logs
Common Pitfalls
| Pitfall | Symptom | Fix |
|---|---|---|
kitty @ returns nothing | Remote control disabled | Set allow_remote_control y in kitty.conf and restart kitty |
| Wrong socket targeted | Commands affect wrong instance | Use kitty @ --to /path/to/socket to specify instance |
| Password not set but required | "Authentication required" | Run kitty @ set-password to create a password |
| Socket not found | "No running kitty instance" | Ensure kitty is running and allow_remote_control is enabled |
| Permissions denied on socket | Can't connect | Check ls -la /tmp/kitty-*/ — socket should be readable by user |
Hands-On Practice
# 1) Enable remote control
echo "allow_remote_control y" >> ~/.config/kitty/kitty.conf
kitty @ load-config
# 2) List current kitty state
kitty @ ls
# 3) Open a new window in /tmp
kitty @ launch --type=window --cwd /tmp
# 4) Open a new tab
kitty @ launch --type=tab --cwd ~
# 5) Check the windows and tabs
kitty @ ls
# 6) Set a larger font size for readability
kitty @ set-font-size 16
# 7) Reset font size
kitty @ set-font-size 12
# 8) Close the window/tab you created
kitty @ close-window