Katheryne

Katheryne is a work-in-progress Discord BOT designed for remote gameplay, computer management, and connectivity via Discord.

Currently, it only supports Linux and Windows, which the latter is still in the early stage.

⚠️ Disclaimer

This BOT prioritizes simplicity and convenience over security and is intended for personal or small-scale use (e.g., providing a "cloud computer" for friends or remotely managing your own device). It is not suitable for large public servers, as I cannot guarantee security at scale.

Only grant permissions to trusted individuals. USE THIS PROGRAM AT YOUR OWN RISK. I am not responsible for any damage resulting from its use.

🎯 Purpose

I originally created this BOT in 2023 to let my friends easily connect to my computer and use features remotely without relying on traditional remote control applications. It also allows me to manage my own computer while away.

The initial implementation worked well, but I lost the original code recently. To prevent this from happening again, I decided to rebuild it and make it open-source.

In October 2025, I began to let my friend play in Windows because of instability (and restrictions) in Linux (because most of their games are Windows-exclusive). Therefore, I decided to port Katheryne into Windows (one more time).

🙋‍♂️ Who is this for?

Katheryne is intended for power users who want to remotely manage or share a gaming PC via Discord - with full control over sessions, user isolation, and system behavior.

It's best suited for:

Self-hosters running a shared or personal "cloud gaming" setup
Users comfortable with command-line configuration
Developers or tinkerers interested in Discord-based automation

This project is not recommended for casual users, public servers, or non-Linux systems. This is a personal tool made open-source for learning and experimentation.

💻 Support

Katheryne works best with KDE Plasma 6 on Linux but is compatible with any distribution using X11 or Wayland.
Windows support is still in a very early stage. Features are not guaranteed to work flawlessly, and bugs/glitches may happen anytime. However, most of the basic features still work as if it's running on Linux.

Intel CPUs + NVIDIA GPUs are also recommended. I haven't tested AMD CPUs/GPUs, so be prepared for potential issues.

Supported Remote Play Applications

Currently, I only write some supporting features for Steam Link / Remote Play.

Moonlight and other tools can be launched via remote execution but are not officially supported, so you have to run the commands manually.

Will there be support for macOS?

No chance. macOS is clearly not designed for gaming, and playing Windows games on macOS is absolutely a nightmare.

✨ Features

These features can be used directly in a Discord server, provided you have the required permissions.

Most of the features work best on Linux.

Note

Any changes with computer settings (physical input lock, brightness, volume, etc.) will be back to normal after restarting the computer. So if you encounter any errors when using the BOT, you just need to restart the computer.

Platform commands coverage

By operating systems

Feature	Linux (X11)	Linux (Wayland)	Windows
Take screenshots	✅	⭕	✅ (1)
View computer stats	✅	✅	✅ (2)
Lock/disable physical input	✅	🔴	❌
Change screen brightness	🔴	🔴	✅ (3)
Mute the host audio	✅	✅	✅
Refocus the game window	✅	❌	✅
Remotely shutdown the computer	🔴	🔴	✅
Set the fan speed	🔴	🔴	❌
Set the CPU governor	🔴	🔴	❌
Check the running process	✅	✅	✅

(1) May experience cropping issues if display size is set to over than 100% (e.g. 125% or 150%).
(2) Viewing Intel GPUs' statistics isn't supported yet.
(3) It's impossible (for me) to turn off the display completely on Windows. I'm using nircmd to handle the display toggle, but the display will be automatically on when moving the mouse or pressing a key.

✅ Fully supported without root permissions
🔴 Supported but requires root permissions
⭕ Supported but not tested
❌ Totally not supported

Tip

On Windows, running the BOT with administrator permissions is recommended, but not required.

Currently, AMD CPUs/GPUs are not properly supported as I don't have any AMD computers.

To protect privacy, some features will only be available when a whitelisted game/application is running.

Running root commands (Linux)

To run commands that require root permissions, you can do one of these ways below:

Grant the permissions for specific commands used by the BOT (recommended)
Running the BOT with sudo permissions
- Using this way may cause some unexpected errors, proceed at your own risk.
- Steam and some games will have some glitches, and tends to have a higher ping when Katheryne is running as root (idk why but it's what it is)
Or don't use these commands at all

List of root commands (Linux)

This is the list of commands requiring root permissions:

Intel GPU stats:
intel_gpu_top
Set display brightness:
brightnessctl set ${pc}%
Set CPU governor:
echo "${governor}" | tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
Set fan speed:
nbfc set -s ${pc}
Physical input locking (Wayland):
evtest --grab /dev/input/event${id} >/dev/null
Physical input device listing (Wayland):
libinput list-devices

For security reasons, you have to find a way to allow these commands for your user by yourself.

📦 Required applications

Linux

General

brightnessctl (for brightness control)
scrot (for X11 screenshot)
wmctrl (for X11 window focusing)
nbfc-linux (for fan control)
libinput-tools (for input devices management)
evtest (for Wayland physical input locking)
rfkill (for enabling/disabling Bluetooth)

Taking screenshots in Wayland

gnome-screenshot (for GNOME-based desktop environments)
spectacle (for KDE Plasma)
grim (for other desktop environments)

Intel GPUs

intel-gpu-tools

Windows

Nothing for now besides Node.js and maybe Git. nircmd will be automatically installed upon setting up the BOT.

🚀 Usage

🧰 Installation

Clone this BOT using this command below or download the latest source code.

git clone https://github.com/Serena1432/Katheryne.git

Change the current directory to the source folder:

cd Katheryne

Install all the dependencies:

npm install

Install all required applications listed in the Required applications section above, depends on your distro and your need.

⚙️ Configuration

Copy the .env.sample file to a new one and rename it to .env, then edit the file and specify the token with the TOKEN variable.
Copy the config.sample folder into a new one, and rename it to config. After that, config the BOT yourself to your liking based on the instructions below.

You can view the example of all configurations in the config.sample folder.

`config/main.json`

Contains the main BOT configuration.

Property	Type	Description
language	`string`	BOT language. Make sure that `strings/${language}.json` exists in the BOT folder.
owner_id	`string`	BOT owner's Discord ID.
prefix	`string`	BOT prefix for message content based commands.
whitelist	`object`	An object with each property as the user ID (key) paired with the Steam account (value), for example `{"693107293516070944": "nicolevianth"}`. See `config.sample/main.json` for example.

`config/computer.json`

Contains the computer configuration.

Property	Type	Description
close_processes	`string[]`	List of processes to be closed upon starting an application.
start_processes	`string[]`	List of processes to be started after exitting applications.
auto_mute	`boolean`	Automatically mute the physical speakers upon starting.
auto_bluetooth_off	`boolean`	Automatically turn off Bluetooth upon starting.
auto_performance_governor	`boolean`	Automatically set the CPU govenor to `performance` upon starting.
auto_max_fan_speed	`boolean`	Automatically set the fan speed to maximum upon starting.
auto_lock_input	`boolean`	Automatically lock the physical inputs upon starting.
evtest_on_x11	`boolean`	Use `evtest` instead of `xinput --disable` to lock the physical input on X11. This way is more stable than xinput but it will require root access.
lock_timer	`boolean`	If `true`, the BOT will rerun the physical input lock/set brightness commands each 10 seconds to further prevent external interference.

`config/steam.json`

Contains the Steam configuration.

Property	Type	Description
executable	`string`	Steam executable path. Usually required if you use Windows, otherwise use `steam` which is set up in `PATH` instead.
default_user	`string`	Default Steam user to be logged in when using the `steam` command. Leave empty to manually select the user upon starting.
wayland_enable_pipewire	`boolean`	Enable PipeWire screen capture when connecting to Steam Remote Play on Wayland.
detach	`boolean`	If `true`, Steam will keep running even when the BOT stops working.

`config/whitelisted_apps.json`

Contains a list of whitelisted apps for all users to run anytime they want.

Is a JSON array containing objects with these properties:

Property	Type	Description
process	`string`	Process name (will be used to detect if the app is running or not)
name	`string`	Display name to be displayed in the BOT status and statistics
alias	`string`	Shortened alias for members to use with the `start` command
command	`object`	An object with each property containing the target Steam account (key) with assigned start command (value), for example `{"default": "/home/murasame/StartGenshin.sh"}`. Use `default` to assign the default command. See `config.sample/whitelisted_apps.json` for more information.
screenshot	`string`	In-game screenshot folder to be monitored. Leave empty if not supported.
localStorage	`string`	The game's LocalStorage/config folder for separating by Steam account username. See LocalStorage/Config data separation support for more information.
channel	`string`	Discord channel ID for in-game screenshots. Unused if `screenshot` isn't set.

`config/logging.json`

Contains the logging configuration.

Property	Type	Description
log_channel	`string`	Discord channel ID to receive logs. Leave empty if you don't want logging.
steam_connection	`string`	Whether to send a log when there's a new Steam Remote Play connection.
high_temperature	`string`	Whether to send a log when the computer temperature is high.
low_battery	`string`	Whether to send a log when the computer battery is low.

🔧 Starting

Running Katheryne as normal user

npm start

Enable further debugging

You can enable further debugging logs that contain all of the command the BOT uses to run by running one of these commands below instead of npm start. Remember that further debugging can output some personal information, and you should be cautious when running it in public.

This is also required when reporting an issue related to the BOT.

For writing the logs directly to the console window, run this command:

npm run debug

For writing the logs to journal on Linux (useful for debugging serious crashes):

npm run debug_journal

Running Katheryne as root on Linux (not recommended)

sudo -E npm start

Autostart

You can of course use your Desktop Environment's Autostart settings (or Task Scheduler on Windows) to start Katheryne automatically after boot.

pm2 is not recommended in my opinion due to it invoking the BOT before starting the DE, so it may cause some unwanted issues.

🧩 Special features

These are advanced features that require additional understanding and specific command arguments.

Assigning a different Steam account for each user

Important

You must log in to all assigned Steam accounts before running the BOT. If an account isn't logged in, Steam will prompt for login when a user runs the steam command!

Don't worry — users won't be able to switch to any account other than the one assigned to them, as long as Steam is started using the specified command (steam -user ${username}). The BOT handles this automatically.

When a different Discord user runs the steam command, the BOT can launch Steam using a specific account assigned to that user. To enable this, you need to map each Discord user ID to a Steam account in the configuration.

For example, to assign the nicolevianth Steam account to user ID 693107293516070944 (this is my Discord ID!), edit your config/main.json file like this:

{
    "language": "en",
    "owner_id": "693107293516070944",
    "prefix": "!",
    "whitelist": {
        "693107293516070944": "nicolevianth" // <---- This!
    }
}

Only users listed in the whitelist object can use the BOT. If you don’t want to assign a specific Steam account to a user, leave the value empty. The BOT will fall back to using the default Steam account defined in config/steam.json.

LocalStorage/Config data separation support

Important

Because the BOT separates data by Steam account username, you must assign a Steam account to each Discord user (even if they don’t use Steam directly).

You need to specify the correct folder that switches the user account when its contents are different (that will require some research from yourself).

Some games store user data and settings in a shared folder within the game directory — even if you use separate Wine prefixes, which can prevent user-specific login information from being properly applied.

To make switching between accounts seamless for users, the BOT allows you to isolate the LocalStorage or any config folder for each account.

Define the target config folder using the localStorage property for each whitelisted app in config/whitelisted_apps.json. For example:

{
    "process": "GenshinImpact.exe",
    "name": "Genshin Impact",
    "alias": "genshin",
    "command": {
        "default": "/home/murasame/StartGenshin.sh"
    },
    "screenshot": "/mnt/GenshinImpact/ScreenShot",
    "localStorage": "/mnt/GenshinImpact/GenshinImpact_Data/SDKCaches/HoYoPass", // <---- This!
    "channel": "1191968934635774034"
}

When a user starts a game using the steam or start command, the BOT:
1. Backs up the current contents of the specified folder to database/${alias}_localStorage_.tar.
2. Extracts the user-specific database/${alias}_localStorage_${steamUsername}.tar file to that folder.

Note

If the user has no previously backed-up data, the BOT will first copy the original folder. The user can then log in to their account and the game will modify the contents, which will subsequently be backed up separately as usual.

When the session ends (via exit, steam exit, or shutdown), the BOT:
1. Backs up the current folder contents to the user-specific .tar file.
2. Restores the original data from database/${alias}_localStorage_.tar, returning the game to the computer owner’s default configuration.

Starting a session on behalf of another user

Note

This feature is available to BOT (computer) owners only.

Sometimes users may not know how to use the BOT, or you may want to launch a session for them manually.

Copy the user's Discord ID, then run the steam ${discordID} or start ${alias} ${discordID} command with that copied Discord ID. For example:

!steam 693107293516070944

or

!start genshin 693107293516070944

The BOT will reply with something like:

Starting with s1432_nbhz's specified information.

The BOT will use the user's assigned Steam account and other relevant settings. That user will also be granted the permission to stop the session or shut down the system, as if they started the session themselves.

Tip

You can also use steam ${steamUsername} or start ${alias} ${steamUsername} to start a session with a specific Steam account, even without a linked Discord account. However, only you (the owner) will be able to stop the session or shut down the computer in that case.

Permissive mode

Add the -permissive argument to the startup command to allow all whitelisted users to stop the session. This is useful when a session is shared among multiple users.

🐞 Known issues

I'm not a skilled expert, so issues are unable to avoid. These are the known issues that I've experienced myself, and I'm not sure if these also work for you.

Windows-specific

There are some known issues which only happen on Windows, but I haven't found the solutions yet:

Physical security features such as turning off the display completely or locking the physical input doesn't work on Windows. This is due to Windows' harsh restrictions.
I haven't found a way to set the CPU/GPU fan speed in Windows yet.
The captured screenshots will be cropped if the user sets the Display Size (DPI) to over 100%.
Some values in the stats and other statistics command will be undefined.
exec command will also output some gibberish characters (which are in fact, indication characters to set the command window colors).
Killing steam.exe alone without killing running games will have a big chance to have Steam auto restarting itself.

Computer crashes after starting game while BOT is running

Try setting high_temperature in config/logging.json to false to disable high temperature warning. This logging may cause crashes on some devices and requires a force restart.

Game crashes when locking/unlocking physical inputs on X11

The xinput commands used on X11 can be unstable on some devices, therefore it crashes the game when executing.

Try setting evtest_on_x11 in config/computer.json to let the lock/unlock commands use evtest instead of xinput. It's more stable but it will require root permissions.

Original LocalStorage/Config data won’t be restored if shutdown without using Katheryne

You just need to make the computer run npm run shutdown_hook before shutting down the computer. For example:

Create a shell script running the shutdown hook first, for example /usr/local/bin/katheryne-shutdown-hook.sh:

#!/bin/bash
cd path/to/Katheryne
/usr/bin/npm run shutdown_hook

Save it and make the .sh executable:

chmod +x /usr/local/bin/katheryne-shutdown-hook.sh

Create a systemd service in /etc/systemd/system, for example katheryne-shutdown-hook.service:

[Unit]
Description=Katheryne shutdown hook
DefaultDependencies=no
Before=poweroff.target shutdown.target reboot.target halt.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/katheryne-shutdown-hook.sh
RemainAfterExit=true

[Install]
WantedBy=poweroff.target shutdown.target reboot.target halt.target

Important

If the localStorage folder is in an external mounted drives, you have to include them in katheryne-shutdown-hook.service, for example:

[Unit]
Description=Katheryne shutdown hook
DefaultDependencies=no
Before=umount.target poweroff.target shutdown.target reboot.target halt.target
RequiresMountsFor=/mnt/secondarydrive

Save it, reload the daemon (or restart the computer) and enable the service:

sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl enable katheryne-shutdown-hook.service

You can test by restarting the computer and checking if it runs properly:

journalctl -b -1 -u katheryne-shutdown-hook.service

🧩 Contributing

This project is open for learning, exploration, and improvement. While Katheryne is primarily a personal project, contributions are welcome as long as they respect its purpose and limitations.

If you’d like to contribute fixes, improvements, or documentation, please read CONTRIBUTING.md for guidelines before submitting a pull request.

📝 License

This BOT is licensed under the MIT License. You are free to use, modify, and distribute it, including for commercial purposes.

Name		Name	Last commit message	Last commit date
Latest commit History 139 Commits
config.sample		config.sample
src		src
.env.sample		.env.sample
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

License

Serena1432/Katheryne

Folders and files

Latest commit

History

Repository files navigation

Katheryne

⚠️ Disclaimer

🎯 Purpose

🙋‍♂️ Who is this for?

💻 Support

Supported Remote Play Applications

Will there be support for macOS?

✨ Features

Platform commands coverage

By operating systems

Running root commands (Linux)

List of root commands (Linux)

📦 Required applications

Linux

General

Taking screenshots in Wayland

Intel GPUs

Windows

🚀 Usage

🧰 Installation

⚙️ Configuration

config/main.json

config/computer.json

config/steam.json

config/whitelisted_apps.json

config/logging.json

🔧 Starting

Running Katheryne as normal user

Enable further debugging

Running Katheryne as root on Linux (not recommended)

Autostart

🧩 Special features

Assigning a different Steam account for each user

LocalStorage/Config data separation support

Starting a session on behalf of another user

Permissive mode

🐞 Known issues

Windows-specific

Computer crashes after starting game while BOT is running

Game crashes when locking/unlocking physical inputs on X11

Original LocalStorage/Config data won’t be restored if shutdown without using Katheryne

🧩 Contributing

📝 License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

`config/main.json`

`config/computer.json`

`config/steam.json`

`config/whitelisted_apps.json`

`config/logging.json`

Packages