Ginseng

Keep your Linux laptop running with the lid closed — controlled from your phone via Tailscale or Telegram.

Ginseng prevents system sleep, idle suspension, and lid-close sleep using systemd-inhibit file descriptor locks. It doesn't modify /etc/systemd/logind.conf or change any permanent system files. When you close Ginseng, standard power management is immediately restored.

I built this to let long-running jobs (model training, compiles, downloads, local dev servers) keep going when I close my laptop and walk away, while giving me a clean web dashboard and Telegram bot to monitor stats and toggle sleep remotely.

• No permanent system changes: Uses systemd-inhibit locks at runtime. Exiting restores default behavior instantly.
• Auto-Guard: Automatically inhibits sleep when specified processes (e.g. python3, node, cargo, docker) are running, and releases the lock when they finish.
• Timers & End-Time: Set keep-awake for a duration (+30m, +1h) or until a specific time (23:30) via the web UI or Telegram.
• Tailscale Web Dashboard: Fast, responsive dark UI for checking CPU load, temperature, RAM, battery, and uptime over your private Tailscale network.
• Telegram Bot: Full remote control from your phone — toggle sleep, set timers, and receive emergency alerts.
• Hardware Safety:
  • Automatically unblocks sleep if battery drops below 10% on battery power.
  • Automatically unblocks sleep if CPU stays above 85°C for more than 3 minutes with the lid closed.

git clone https://github.com/mimmocrazy/Ginseng.git
cd Ginseng
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

If you want remote control via Telegram:

1. Create a bot with @BotFather and copy the token.
2. Get your user ID from @userinfobot.
3. Create a .env file:

cp .env.example .env

And fill in your credentials:

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_USER_ID=your_numeric_user_id
WEB_PORT=7464

Note: Ginseng whitelists TELEGRAM_USER_ID, so only you can control the bot.

# Start Ginseng
ginseng
# Start silently in background
ginseng --silent
# Custom port or config
ginseng --port 8080
ginseng --config config.toml

Open http://localhost:7464 or http://<your-tailscale-ip>:7464 on your phone/browser.

To keep Ginseng running in the background automatically:

mkdir -p ~/.config/systemd/user
cp ginseng.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now ginseng.service

You can customize watched processes and safety thresholds in config.toml:

[watcher]
# Keep system awake while any of these are running:
processes = ["python3", "node"]
auto_inhibit = true
[safety]
battery_critical_threshold = 10 # Unblock sleep if battery <= 10%
temp_alert_threshold = 85 # Alert if CPU >= 85°C
temp_sustained_seconds = 180 # Release lock after 3 mins of overheat
thermal_emergency_sleep = true
[web]
host = "0.0.0.0"
port = 7464

Distributed under the MIT License. Copyright © 2026 Mimmo.