Metadata-Version: 2.3
Name: hedockerssh-tgbot
Version: 1.0.0
Summary: Telegram bot for managing hedockerssh SSH containers
Author: undefined
Author-email: undefined <hestudio@hestudio.net>
Requires-Dist: hedockerssh==1.1.1
Requires-Dist: python-telegram-bot[job-queue]>=21.0
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# hedockerssh-tgbot

Manage [hedockerssh](https://pypi.org/project/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](https://github.com/hestudio-community/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](https://docs.astral.sh/uv/)
- A Telegram bot token from [@BotFather](https://t.me/BotFather)
- Your Telegram user ID from [@userinfobot](https://t.me/userinfobot)

## Install

Install the bot as a uv tool (recommended):

```bash
uv tool install hedockerssh-tgbot
```

Then start it:

```bash
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:

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

| Key | Required | Description |
| --- | --- | --- |
| `TELEGRAM_BOT_TOKEN` | Yes | Bot token issued by [@BotFather](https://t.me/BotFather) |
| `DOCKERSSH_ADMIN_IDS` | Yes | Telegram user IDs allowed to use the bot. Comma-separated string or JSON array |
| `HOST` | No | Domain or IP shown in SSH instructions. Auto-detected when empty |

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.

| Command | Description |
| --- | --- |
| `/new` | Create an SSH container via a wizard (image, platform, port, password) |
| `/list` | List containers — tap one to open its detail view |
| `/help`, `/start` | Show help |
| `/env_list` | Show installed and supported platform environments |
| `/env_install` | Install a platform environment (runs a build, may take minutes) |
| `/env_remove` | Remove a platform environment |
| `/cancel` | Cancel the current dialog |

### 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:

```bash
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.
