Pocket AI Agent on Android with Hermes

Turn an old Android phone into a personal AI server using Termux and Hermes.

Introduction

30 Second Summary

Most of us have an old Android phone collecting dust in a drawer. It still has a working processor, Wi-Fi, and enough power to run a personal AI assistant.

In this project, you will install Hermes Agent on your old Android phone using Termux and connect it to a free AI model through OpenRouter. Then you will wire it up to a Telegram bot so you can chat with your AI agent from any device.

What You'll Build

Picture messaging a Telegram bot from your main phone and getting back intelligent AI responses, all powered by your old phone sitting on a shelf with no laptop or cloud server involved.

By the end of this project, you'll have:

A full AI conversation running in your phone's terminal that responds to your questions in real time.
A Telegram bot you can message from any device that replies with AI-generated answers powered by your pocket server.
A dedicated AI device running independently on your old phone without needing a laptop or cloud server.
Secret Mission: A resilient setup with a second AI provider and auto-start that keeps your agent running across reboots.

Are there any prerequisites?

You need an Android phone running Android 7.0 or higher with a Wi-Fi connection and a free Telegram account. A second device like your main phone or a computer is helpful for testing the bot but not strictly required.

Before We Start

Before we dive in, let's lock in what you're about to build and why it matters to you. Naming your goal now turns the rest of the project from following instructions into building something you chose.

Set Up Termux on Your Android Phone

Your Android phone does not come with a terminal or package manager out of the box. To run Hermes Agent, you need a Linux-like environment where you can install software and execute commands.

Termux turns your Android phone into exactly that. It gives you a full terminal with its own package manager, so you can install tools just like you would on a Linux computer. In this step, you will install Termux, update its packages, and configure Android to keep it running in the background.

In this step, get ready to:

Install F-Droid and Termux on your Android phone.
Update packages and install curl and git.
Configure battery settings to keep Termux alive in the background.

Install F-Droid and Termux

F-Droid is an open-source app store for Android. You need it because the Google Play Store version of Termux is outdated and broken.

On your Android phone, open your web browser and go to https://f-droid.org.
Tap the download button to download the F-Droid APK file.
Open the downloaded file and install it. Android may ask you to allow installs from unknown sources. Tap Settings when prompted and enable the toggle, then go back and tap Install.
Open F-Droid once it finishes installing.
Tap the search icon and search for Termux.
Tap Install on the Termux app listing.
Once installed, open Termux. You should see a black terminal screen with a blinking cursor.

Do not install Termux from the Google Play Store

The Play Store version of Termux is deprecated and no longer receives updates. Its package repositories are broken, so commands like pkg install will fail. Always use the F-Droid version.

Can't find Termux in F-Droid?

F-Droid needs to update its repository index the first time you open it. Wait for the initial sync to finish (you will see a progress indicator), then search again.

If it still does not appear, open this direct link in your phone's browser: https://f-droid.org/en/packages/com.termux/.

help me install Termux from F-Droid on my Android phone

Update packages and install dependencies

Termux ships with a minimal set of tools. You need to update the package list and install curl (for downloading scripts) and git (for version control).

Update your package list and upgrade existing packages by running this command in Termux:

pkg update && pkg upgrade -y

What does this command do?

pkg update refreshes the list of available packages from the Termux repository mirrors.
pkg upgrade -y upgrades all installed packages to their latest versions. The -y flag automatically confirms the upgrades.

Termux will test available mirrors and download updates. This may take a few minutes depending on your internet speed.

Once the update finishes, install curl and git by running:

pkg install -y curl git

You should see output showing the packages being downloaded and installed, ending with a success message.

Seeing repository errors?

If you see errors mentioning a repository that is not signed or cannot be reached, Termux picked a mirror that is temporarily down. Run termux-change-repo to switch to a different mirror, then try the update again.

In the mirror selection screen, use the arrow keys to navigate and press Space to select a mirror (not Enter). Then press Enter to confirm.

help me fix Termux repository errors when running pkg update

Prevent Android from killing Termux

Android aggressively kills background apps to save battery. If Termux gets killed, your AI agent stops responding. You need to exempt Termux from battery optimization.

Open the Settings app on your Android phone.
Tap Apps (or Apps & notifications on some devices).
Find and tap Termux in the app list.
Tap Battery (or Battery usage).
Select Unrestricted (the exact wording varies by device, but look for the option that allows unlimited background activity).

Why does this matter?

Without this setting, Android may suspend Termux after a few minutes of screen-off time. When you connect Telegram in Step 4, you need Termux to stay awake so your bot can respond to messages.

Can't find the battery setting?

Different Android manufacturers label this setting differently. On Samsung, look for Battery optimization and set Termux to Not optimized. On Xiaomi, check Battery saver and set No restrictions.

help me find the battery optimization setting for Termux on my Android phone

Before you move on, do you think the curl package is still available after all those configuration changes? Let's verify.

Switch back to Termux and confirm your packages are installed by running:

pkg list-installed | grep curl

You should see curl listed in the output, confirming the package is installed and ready.

Your phone now has a working Linux terminal with everything Hermes needs. Next up, you will install Hermes Agent and bring your pocket AI to life.

Install Hermes Agent

Your Android phone now has a working Linux terminal with all the system packages you need. The next step is to give it intelligence.

Right now, Termux is a powerful but empty shell. Hermes Agent is an open-source AI agent framework by Nous Research that turns it into something that can understand and respond to natural language.

In this step, get ready to:

Install Hermes using the official one-line installer.
Verify the installation with hermes version and hermes doctor.
Start a Hermes session.

Run the official one-line installer

The Hermes installer handles everything for you. It installs system packages, creates a Python virtual environment, downloads the Termux-tested bundle, and links the hermes command to your PATH.

Install Hermes by running the official installer script in Termux (this takes 5-15 minutes depending on your network speed and phone performance):

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

What does this command do?

This single command downloads and runs the official Hermes install script. The script does several things automatically:

Uses pkg to install any additional system packages Hermes needs (Python, clang, rust, and others).
Creates a Python virtual environment to keep Hermes dependencies isolated.
Installs the Termux-tested bundle, which includes the CLI, Telegram gateway, MCP support, and memory features.
Links the hermes binary to your PATH so you can run it from anywhere.

You will see a lot of output scrolling by as packages download and compile. Let it run until you see a completion message.

Installer seems stuck or fails?

Make sure your phone is connected to Wi-Fi. Mobile data can be unreliable for large downloads.
If you see a storage error, check that your phone has at least 3 GB of free space.
If the installer fails partway through, run the same curl command again. The script is designed to resume where it left off.

Still stuck? Help me troubleshoot the Hermes installer failing on Termux.

Verify the installation

The installer finished, but you need to confirm that the hermes command is actually accessible and the environment is healthy.

Before you run the next commands, what do you expect to see if Hermes installed correctly?
Verify your installation by running:

hermes version

You should see a version number printed. This confirms the binary is on your PATH and executable.

Now check your environment health by running:

hermes doctor

This scans your environment and reports any missing dependencies. You should see no critical errors.

Seeing command not found?

Close Termux completely (swipe it away from your recent apps) and reopen it. This refreshes your PATH so the new hermes binary is found.
If that does not help, the installer may not have finished successfully. Scroll up in your terminal and look for error messages near the end of the installer output.

Need more help? Help me fix hermes command not found after running the installer.

Start your first Hermes session

Hermes is installed and the doctor check passes. Time to see what happens when you actually start a conversation.

Before you run this, do you think Hermes will be able to respond to your messages?
Start Hermes by running:

hermes

You will see an error or empty response indicating that no AI provider is configured. Hermes cannot generate any answers because it has no connection to an AI model yet.

Why did that fail?

Hermes is the framework that orchestrates conversations, tools, and memory. But it does not contain an AI model itself.

It needs a provider (like OpenRouter, which offers free models) to send your messages to and get responses from. You will connect one in the next step.

Press Ctrl+C or type /quit to exit back to the terminal prompt.

Hermes is installed and healthy. Next up, you will connect it to a free AI model so it can actually think and respond.

Configure an AI Provider and Chat

In the last step, you installed Hermes and tried running it. It started up but couldn't actually respond because no AI model was connected.

Hermes is a framework, not a model. It needs a connection to an AI provider that hosts the actual language model. You will connect it to OpenRouter, which gives you access to free models at no cost.

In this step, get ready to:

Create a free OpenRouter account and generate an API key.
Configure Hermes to use a free AI model through the hermes model wizard.
Have your first AI conversation in the Termux terminal.

Create an OpenRouter account and get an API key

OpenRouter is a unified API gateway that lets you access hundreds of AI models through a single key. Several of those models are completely free to use.

On any device with a browser (your computer or the Android phone itself), go to https://openrouter.ai.
Click Sign Up and create a free account using your email or a Google/GitHub login.
Once signed in, navigate to your API Keys page (you can go directly to openrouter.ai/keys).
Click Create New Key.
Give it any name (for example, hermes-phone) and click Create.
Copy the key that appears. It starts with sk-or-. Keep this in your clipboard or paste it somewhere temporarily.

Why is the key only shown once?

OpenRouter only displays the full key at creation time. If you lose it, you will need to delete that key and create a new one. Paste it somewhere safe before closing the page.

Keep your API key secret

Never share your API key publicly or commit it to a repository. Hermes stores it in a local file on your phone, which is fine for personal use.

Run the model setup wizard

Hermes has a built-in wizard that walks you through choosing a provider and model. It handles saving your key and configuration automatically.

Switch back to Termux on your Android phone and start the model wizard by running:

hermes model

What will the wizard ask?

The wizard is interactive. It prompts you to select a provider, enter your API key, and choose a model. Here is what to expect at each prompt:

Provider selection: choose OpenRouter from the list.
API key prompt: paste the sk-or- key you copied earlier.
Model selection: the wizard shows available models. Pick any model marked as free ($0 pricing). Meta Llama or Mistral variants are good choices.

Select OpenRouter when the provider list appears.
Paste your API key when prompted.
Choose a free model from the list. Look for models showing $0 pricing next to their name.

The wizard saves your provider choice to ~/.hermes/config.yaml and your API key to ~/.hermes/.env.

Wizard not showing any free models?

Free model availability can change. If no free models appear, scroll through the full list. Models from Meta (Llama) or Mistral frequently have free variants. You can also browse openrouter.ai/models in your browser and filter by price to find current free options.

Help me find free models in the Hermes wizard

Have your first conversation

With a provider configured, Hermes can now generate real responses. Time to test it.

Before you run Hermes, think: do you expect it to respond this time, or fail like it did in the previous step?
Start Hermes by running:

hermes

Type a message like What is Termux? and press Enter.

Hermes responds with an AI-generated answer. You now have a working AI agent running on your Android phone.

Try asking one or two more questions to confirm it works consistently.
When you are done, press Ctrl+C or type /quit to exit the chat session.

Getting an error instead of a response?

If you see an authentication or connection error, your API key may not have been saved correctly. Run hermes model again and re-enter your key. Make sure you paste the full key including the sk-or- prefix.

If the response is very slow, this is normal on an older phone over Wi-Fi. The model runs remotely on OpenRouter's servers, so speed depends on your network connection.

Help me fix my OpenRouter connection

Your old phone is now a working AI device. Next up, you will connect a Telegram bot so you can chat with Hermes from anywhere in the world without needing to look at the phone screen.

Connect Telegram as Your Chat Interface

Your AI agent is live and responding in Termux. You can type a question, hit Enter, and get a real AI-generated answer. But right now, chatting means physically looking at your old phone's screen and typing on its keyboard.

Telegram solves this by giving your agent a bot interface you can message from any device. In this step, you'll create a Telegram bot and connect it to Hermes so your pocket AI becomes reachable from your main phone, a computer, or anywhere with internet.

In this step, get ready to:

Create a Telegram bot using @BotFather.
Configure the Telegram gateway in Hermes.
Send your first message to the bot and receive an AI-powered response.

Create a Telegram bot

Every Telegram bot starts with @BotFather, the official Telegram bot for creating and managing other bots. You'll ask it to create a new bot and it will give you an authentication token.

Open Telegram on any device (download from https://telegram.org if you don't have it yet).
Tap the search bar at the top of Telegram.
Type @BotFather and select it from the results.
Tap Start at the bottom of the chat to begin.
Send the command /newbot to BotFather.

What does BotFather ask you?

BotFather will prompt you for two things. First, a display name for your bot (this can be anything, like "My Hermes AI"). Second, a unique username that must end in "bot" (for example, myhermes_bot or HermesAIBot).

The username must be 5-32 characters and can only include Latin letters, numbers, and underscores. You cannot change this username later, so choose carefully.

Enter a display name when BotFather asks (for example, "Hermes AI").
Enter a username ending in "bot" when prompted (for example, myhermes_bot).
BotFather replies with your bot token. Copy this token and keep it safe. Anyone with this token can control your bot.

Keep your bot token private

Your bot token looks like a long string of numbers, a colon, and random characters. Do not share it publicly or commit it to version control.

Now you need your own numeric Telegram user ID. This tells Hermes which Telegram account is allowed to talk to the bot.

In Telegram, tap the search bar and type @userinfobot.
Select it from the results and tap Start.
The bot immediately replies with your numeric user ID. Copy this number.

What is this numeric user ID?

Your Telegram user ID is a permanent number assigned to your account. It never changes, even if you update your username or display name. Hermes uses it to restrict who can send messages to your bot.

Configure the Telegram gateway

With your bot token and user ID in hand, you need to tell Hermes about them. You'll add both values to the Hermes environment file, then run the gateway setup wizard.

Switch back to Termux on your Android phone.
Add your bot token and user ID to the Hermes environment file by running these commands:

echo 'TELEGRAM_BOT_TOKEN=your-bot-token-here' >> ~/.hermes/.env
echo 'TELEGRAM_ALLOWED_USERS=your-user-id-here' >> ~/.hermes/.env

Replace your-bot-token-here with the token you copied from BotFather.
Replace your-user-id-here with the numeric user ID from @userinfobot.

Confirm both values were written by running:

grep TELEGRAM ~/.hermes/.env

You should see two lines: one containing TELEGRAM_BOT_TOKEN and one containing TELEGRAM_ALLOWED_USERS, each with the values you pasted.

Not seeing both lines?

If only one line appears or neither shows, you may have a typo in the variable name. Open the file with cat ~/.hermes/.env to see the full contents. Check for extra spaces around the = sign or missing quotes in your echo commands.

Help me fix my Hermes .env file for Telegram

Now run the gateway setup wizard:

hermes gateway setup

What happens during gateway setup?

The wizard asks which messaging platform you want to connect. Select Telegram when prompted. Hermes reads your TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS from ~/.hermes/.env and saves the gateway configuration to ~/.hermes/config.yaml.

When the wizard asks for a platform, select Telegram.

Start the gateway and test

The gateway is configured. Now you'll start it and see if your bot actually responds to messages from Telegram.

Start the Telegram gateway by running:

hermes gateway start

Hermes begins listening for incoming Telegram messages. The terminal shows that the gateway is active.

Before you send a message to your bot, take a guess. Do you think the bot will respond instantly, or will there be a noticeable pause while Hermes sends your message to OpenRouter and waits for the AI model to reply?

Open Telegram on your main phone or computer.
Search for the bot username you created (the one ending in "bot").
Tap Start to begin a chat with your bot.
Send a message like "What is Termux?" and wait for the response.

Within a few seconds, your bot replies with an AI-generated answer. The response travels from Telegram to Hermes on your old Android phone, out to OpenRouter's AI model, and back through the same chain to your Telegram chat.

Bot not responding?

Check that hermes gateway start is still running in Termux. If you switched apps, Android may have suspended the process. Return to Termux and check for error messages.

Make sure your TELEGRAM_ALLOWED_USERS value matches your exact numeric user ID. If it doesn't match, Hermes ignores messages from your account.

Also verify your bot token is correct. A single missing character causes authentication failure. Run cat ~/.hermes/.env and compare the token against what BotFather sent you.

Help me debug my Hermes Telegram gateway

Secret mission

Add a Second Provider and Keep Hermes Always On

What if your AI provider goes down mid-conversation? And what happens when your phone restarts? In this bonus challenge, you will add a second AI provider for resilience and configure Hermes to auto-start on boot, turning your old phone into a true always-on AI server.

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely. This project runs entirely on your Android phone using free models, so there are no ongoing cloud costs.

Resources you used:

Hermes Agent (installed in Termux with config files in ~/.hermes/).
Boot script at ~/.termux/boot/start-hermes.sh.
OpenRouter account and API key.
Telegram bot (created via @BotFather).
Termux:Boot app (installed via F-Droid).
Termux app (installed via F-Droid).
F-Droid app.

Keep everything running

No action needed. Choose this if you want your Telegram bot to stay active and respond to messages around the clock.

Your old phone continues running Hermes in the background.
The Telegram bot stays reachable from any device.
The phone uses power continuously, so keep it plugged in.
F-Droid, Termux, and Termux:Boot remain installed on the device.

Pause - I'll come back to this later

Stop the gateway process and disable auto-start to free up battery and memory. Your configuration files stay on the phone for when you return.

Open Termux and press Ctrl+C to stop the running gateway process.
Rename the boot script so it does not run on restart:

mv ~/.termux/boot/start-hermes.sh ~/.termux/boot/start-hermes.sh.disabled

When you are ready to resume, rename it back:

mv ~/.termux/boot/start-hermes.sh.disabled ~/.termux/boot/start-hermes.sh

Your Telegram bot will stop responding until you restart the gateway.
All config files, API keys, and apps remain intact for later use.

Delete - I don't want to use this again

Remove all project resources from the phone and revoke your external accounts. This cannot be undone.

Delete your Telegram bot. Open Telegram, start a chat with @BotFather, and send:

/deletebot

Follow the prompts to select your bot and confirm deletion. This frees the bot username permanently and cannot be undone.
Revoke your OpenRouter API key. Go to https://openrouter.ai, open your API keys page, and delete the key you created for this project.
If you want to delete the OpenRouter account entirely, go to Settings, click Manage Account, select the Security tab, and use the delete option there.
Remove all Hermes files and configuration from Termux:

rm -rf ~/.hermes

Remove the boot script directory:

rm -rf ~/.termux/boot

Uninstall Termux:Boot. Go to Android Settings, select Apps, find Termux:Boot, and tap Uninstall.
Uninstall Termux. Go to Android Settings, select Apps, find Termux, and tap Uninstall. This also removes all data stored inside Termux.
Uninstall F-Droid. Go to Android Settings, select Apps, find F-Droid, and tap Uninstall.
Revert the battery setting. Go to Android Settings, select Apps, find Termux (if still listed), select Battery, and set it back to Optimized. If Termux is already uninstalled, this setting is removed automatically.

Nice Work!

You just turned an old Android phone into a fully operational AI server. Your pocket device now runs Hermes Agent, responds to natural language, and is accessible from anywhere in the world through Telegram.

Here's what you accomplished:

Installed Termux and transformed an old Android phone into a Linux environment capable of running developer tools and AI frameworks.
Installed Hermes Agent and connected it to a free AI model through OpenRouter, giving your phone the ability to generate intelligent responses from the terminal.
Created a Telegram bot and wired it to Hermes so you can message your AI agent from any device, anywhere in the world.
Secret Mission: Added a second AI provider for resilience and configured Termux:Boot so Hermes auto-starts and survives reboots.

Ready to quiz yourself?