hedockerssh-tgbot

Manage hedockerssh — Docker containers exposed as SSH connections — through a Telegram bot.

Built directly on top of the hedockerssh.services API: every Docker operation the bot performs goes through the official service layer of DockerSSH.

Features

• Container lifecycle — start / stop / restart / delete with inline buttons and confirmation for destructive actions
• Guided container creation (/new) — pick a local Docker image, platform, port and password step by step; everything optional with sensible defaults
• Password handling — auto-generated or custom passwords, sent in a separate message that self-deletes after 60 seconds; the message containing a custom password is deleted from the chat immediately
• Platform environment management — list, install (build) and remove the platform runtimes DockerSSH needs
• Pagination — every list shows 5 items per page with prev/next buttons
• Access control — strict user-ID whitelist; nobody else can even talk to the bot
• Robust service bridge — synchronous Docker calls run in worker threads with stdout capture (no password leaks to logs), timeouts and normalized error codes mapped to human-readable messages

Requirements

• Linux or macOS with a working Docker daemon (incl. buildx) — the bot runs on the Docker host
• uv
• A Telegram bot token from @BotFather
• Your Telegram user ID from @userinfobot

Install

Install the bot as a uv tool (recommended):

uv tool install hedockerssh-tgbot

Then start it:

dockerssh-tgbot

Run dockerssh-tgbot again after editing the configuration file; configuration is read at startup.

Configuration

Configuration lives in a JSON file next to the DockerSSH data:

• Linux: /var/lib/dockerssh/tgbot.json
• macOS: ~/Library/Application Support/dockerssh/tgbot.json

The file is created with an empty template on first start — fill it in and start again:

{
  "TELEGRAM_BOT_TOKEN": "123456:ABC-...",
  "DOCKERSSH_ADMIN_IDS": "123456789,987654321",
  "HOST": ""
}

Real environment variables (TELEGRAM_BOT_TOKEN, DOCKERSSH_ADMIN_IDS, HOST) override the values in the file.

Migration: if a legacy .env file exists in the working directory on first start, its values are imported into tgbot.json automatically.

Commands

Commands are registered with Telegram, so they show up in the menu button next to the input field.

Creating a container

1. /new lists local Docker images (or pass one directly: /new ubuntu:24.04)
2. Choose a platform — auto-detect or one of the installed runtimes
3. Choose a port — auto-assign or a specific 1-65535 port
4. Choose a password — auto-generate or type your own (6-64 chars)
5. Confirm — the bot replies with the ssh connection line and sends the password in a self-deleting message

Managing containers

/list shows containers 5 per page. Tapping one opens a detail view with status, image, platform and the actions ▶️ Start / ⏸ Stop / ♻️ Restart / 🔑 Reset password / 🗑 Delete (with confirmation). Resetting a password offers the same auto-generate / manual input flow as /new.

Security

• Only whitelisted user IDs may interact with the bot; all others are dropped
• Password-bearing messages are deleted: custom passwords immediately after reading, generated passwords 60 seconds after sending
• Service-layer stdout (which prints passwords in plain CLI mode) is captured and never reaches the chat or logs
• The bot inherits your Docker permissions — treat the bot token like a shell account

Development

Run from source:

git clone <this-repo> && cd hedockerssh-tgbot
uv sync
uv run dockerssh-tgbot

Project layout:

src/hedockerssh_tgbot/
├── __init__.py            # main(): config, wiring, command registration, polling
├── config.py              # tgbot.json loading, .env migration, validation
├── auth.py                # global whitelist gate (ApplicationHandlerStop)
├── bridge.py              # sync→async bridge: threads, stdout capture, timeouts
├── ui.py                  # error mapping, pagination, secrets, HTML helpers
└── handlers/
    ├── containers.py      # /list, /new wizard, detail view, password flows
    └── envs.py            # platform environment commands

Disclaimer

SSH passwords travel through Telegram servers. Assess the risk for your threat model before using this in production.