Home Agent Telegram Bot

Welcome to the Home Agent project! This is an open-source Telegram bot built with Python and Poetry, designed to automate tasks and serve as a learning platform for bot development.

It is an educational and functional project, with the possibility to install as a systemd service and restart remotely via bot command.

Features

• Built with Python and Poetry
• Easily extendable and open for contributions
• Designed for beginners and enthusiasts
• Can be installed as a systemd service and restarted remotely via Telegram commands

Getting Started

Prerequisites

• Python 3.11+ (not tested, but expected to run on 3.9+)
• Basic knowledge of Poetry
• Opencode AI cli
• A Telegram bot created (see below)

Creating a Telegram Bot

1. Open Telegram and search for @BotFather.
2. Start a conversation and use /newbot to create your bot.
3. Follow the instructions and save your bot token.
4. Paste the token into your .env file.

Set up your and run

1. Install dependencies with Poetry:

   poetry install --no-root

2. Copy .env.sample to .env and fill in your Telegram Bot credentials.
3. Start the app:

   poetry run python -m telegram_reader.main

Restarting the service remotely

This project can be installed as a user-scoped systemd service and restarted with a Telegram command.

Environment variables

Add these values to your .env file:

TELEGRAM_BOT_TOKEN=your-token-here
TELEGRAM_ADMIN_USER_IDS=123456789
RESTART_COMMAND=bash ./scripts/restart-home-agent.sh

• TELEGRAM_ADMIN_USER_IDS is a comma-separated list of Telegram user IDs allowed to run /restart
• RESTART_COMMAND is the fixed local script that restarts the service

You can discover your Telegram user ID by sending this command to the bot:

/whoami

Install the user service

Copy the service files into your user systemd directory:

mkdir -p ~/.config/systemd/user
ln -sf /home/repos/home-agent/systemd/home-agent.service ~/.config/systemd/user/home-agent.service
ln -sf /home/repos/home-agent/systemd/opencode-server.service ~/.config/systemd/user/opencode-server.service

If Poetry is installed elsewhere, update ExecStart in systemd/home-agent.service first.

The provided service files also load environment variables from %h/repos/home-agent/.env.

Then enable and start the services:

systemctl --user daemon-reload
systemctl --user enable opencode-server.service home-agent.service
systemctl --user start opencode-server.service home-agent.service
systemctl --user status opencode-server home-agent
journalctl --user -u opencode-server -e
journalctl --user -u home-agent -e

To keep user services available after logout, enable lingering once:

loginctl enable-linger "$USER"

Restart via Telegram

Send this command to the bot:

/restart

If your Telegram user ID is listed in TELEGRAM_ADMIN_USER_IDS, the bot will run the fixed restart script and systemd --user will restart the service. If the user is not authorised, the bot stays silent and only logs the attempt locally.

Example in Action

Below you can see Home Agent in use:

Telegram request:

App response:

Contributing

This project is open for contributions! Whether you're a beginner or an experienced developer, your input is welcome. Please follow best practices and submit pull requests for review.