How to Use a USB Drive as a Portable AI Agent

Understand the Concept

What Does It Mean to Put an AI Agent on a USB Drive?

A portable AI agent is an agent whose important state follows you from one computer to another. Instead of leaving its configuration and history in the default home directory of one laptop, you deliberately place the agent’s data directory on a removable drive. When Hermes starts, it reads that directory and finds the same provider settings, memories, sessions, skills, personality files, logs, and messaging configuration.

Hermes Agent makes this possible through HERMES_HOME. The official Hermes environment-variable reference describes it as an override for the normal ~/.hermes configuration directory. It also scopes the gateway PID and service identity. In practical terms, setting HERMES_HOME to a folder on the USB tells Hermes to treat that folder as its home.

This distinction matters because a USB drive is storage, not a replacement for the host computer. The following components are still provided elsewhere:

• Compute: The connected computer provides its CPU, RAM, and possibly GPU.
• Runtime: Hermes, Python, Git Bash, Node.js, and optional browser or audio dependencies must be installed or supplied in an OS-compatible form.
• Model inference: A cloud provider such as OpenRouter, Nous Portal, OpenAI, Anthropic, or Gemini processes requests unless you connect Hermes to a local model server.
• Network: Cloud models, Telegram, web search, browser tools, and updates require internet access.
• Power: The agent stops when the computer shuts down, sleeps, or the USB is disconnected.

The result is best described as a portable agent workspace. Your agent identity and working state travel with the drive, while the computer you plug it into becomes the temporary execution environment.

Choose the Right Deployment

Portable USB AI Agent vs. Hermes on a Hostinger VPS

A USB drive and a VPS solve different problems. A removable drive gives you physical possession of the agent’s state and makes it convenient to move a workspace between trusted machines. A VPS gives the agent a permanent online computer, which is much better when you want Telegram access, scheduled jobs, automations, or long-running tasks at any hour.

You can use both. Keep a portable profile on your USB for travel or local work, and run a separate always-on profile on a VPS for Telegram and automations. Do not run both gateways with the same Telegram bot token simultaneously; Telegram bot credentials should belong to one active gateway at a time.

Prepare First

What You Need for a Portable Hermes AI Agent

A reliable setup starts with better storage and a clear security plan. You do not need an enormous drive, but a cheap, slow promotional USB stick is a poor place for an application that regularly updates databases, sessions, logs, caches, and configuration files.

Which USB File System Should You Use?

Choose the file system based on the operating systems you actually intend to use. For a tutorial that moves data among Windows, Linux, and macOS, exFAT is the practical compatibility choice. All three systems can read and write it without the same friction associated with Linux-native or Windows-native formats.

Video Walkthrough

Watch: Turning a USB Drive Into a Portable Hermes AI Agent

The embedded video demonstrates the portable launcher workflow, provider and Telegram setup, and tests on multiple operating systems. The written steps below add more explanation around HERMES_HOME, file-system tradeoffs, credential safety, and dependable launcher design.

Complete Tutorial

How to Use a USB Drive as a Portable AI Agent: Step by Step

Step 1: Back Up and Identify the Correct USB Drive

Connect the drive directly to the computer when possible. Open Disk Management on Windows, Disk Utility on macOS, or Disks/GParted on Linux. Match the manufacturer’s name and total capacity with the physical drive. Back up any files you want to keep because the formatting step erases the selected volume.

Give the volume a recognizable name such as HERMES_USB. A stable label makes the drive easier to identify in File Explorer, Finder, Linux file managers, and launcher scripts. The label is more useful than assuming it will always be assigned the same Windows drive letter.

Step 3: Create a Clear Portable Folder Structure

At the root of the drive, create a structure that separates agent state from operating-system launchers and backups. For example:

HERMES_USB/ ├── hermes-data/ │ ├── config.yaml │ ├── .env │ ├── memories/ │ ├── sessions/ │ ├── skills/ │ └── logs/ ├── launchers/ │ ├── Start-Hermes-Windows.ps1 │ ├── start-hermes-linux.sh │ └── start-hermes-macos.sh ├── installers/ ├── backups/ └── README-FIRST.txt

The hermes-data directory is the important portable state. The launchers directory contains small scripts that point Hermes at that state. The optional installers directory can contain trusted, verified installation resources, but you should still check the official Hermes repository for current releases rather than relying forever on an old copy.

Step 5: Point Hermes at the USB with HERMES_HOME

Set HERMES_HOME to the absolute path of the USB’s hermes-data folder before starting Hermes. The launcher should calculate that path from its own location. This is what makes it resilient when Windows assigns a new drive letter or a Linux desktop mounts the drive under a different username.

Run hermes setup only after HERMES_HOME is set. Otherwise, the setup wizard may save configuration to the computer’s normal home directory instead of the USB.

Step 6: Configure an AI Model Provider

Launch the setup wizard and choose a provider. Hermes supports many providers and any suitable OpenAI-compatible endpoint. Common options include OpenRouter, Nous Portal, OpenAI, Anthropic, Google Gemini, and a local server such as Ollama, LM Studio, llama.cpp, vLLM, or SGLang.

hermes model

When you enter an API key through the Hermes configuration flow, verify that it is being written under the USB’s hermes-data folder. The normal secret file is .env. The official documentation recommends using hermes config set because Hermes then stores secrets and nonsecret settings in their appropriate files.

hermes config set OPENROUTER_API_KEY your_key_here

Use a dedicated key for the portable agent. Set a provider-side budget or rate limit where available. This makes it easier to revoke one credential without interrupting your other applications if the drive is misplaced.

Step 7: Start a Local Hermes Chat and Confirm Persistence

Start Hermes from the portable launcher and ask it a harmless test question. Add a memorable, nonsecret preference, end the session, close the terminal, and relaunch the agent from the drive. Confirm that the session and memory remain available.

hermes chat

Next, inspect the USB’s hermes-data folder. You should see the files and directories being updated there, not in the computer’s default ~/.hermes or Windows local application-data location. If both locations change, stop and correct the launcher before continuing.

Step 8: Safely Eject and Test on a Second Operating System

Stop the Hermes gateway and close every terminal that is using the drive. Wait for writes to finish, then use the operating system’s eject function. Removing an exFAT drive while a session database or log is being updated can corrupt files.

Connect the drive to a second trusted computer. Install a compatible Hermes runtime if necessary, run the correct launcher for that operating system, and verify that it opens the same portable profile. You may need to grant execution permission to shell launchers on Linux or macOS:

chmod +x launchers/start-hermes-linux.sh chmod +x launchers/start-hermes-macos.sh

Step 9: Repeat the Test on macOS if Needed

macOS can read and write exFAT, so the same data directory can be mounted there. However, macOS security may quarantine downloaded scripts, and Apple Silicon requires ARM-compatible binaries when you bundle runtimes. A normal Hermes installation plus a small launcher is generally more reliable than trying to carry one executable for every machine.

Reliable Startup

Portable Hermes Launcher Examples

The following examples assume the scripts live inside HERMES_USB/launchers/ and the agent data lives in the sibling directory HERMES_USB/hermes-data/. They calculate the data path relative to the script. Adjust the folder layout if yours is different.

Windows PowerShell Launcher

Save it as Start-Hermes-Windows.ps1. If PowerShell’s execution policy blocks it, do not permanently weaken system security without understanding the consequence. You can open PowerShell, inspect the file, and run it for the current process with an appropriate temporary policy approved by the computer owner.

Linux or macOS Shell Launcher

You can change the final command to hermes, hermes --tui, or a gateway command depending on the interface you want. Keep the first version simple and prove that persistence works before adding menus, automatic updates, background services, or dependency installation.

Remote Chat

How to Connect the Portable AI Agent to Telegram

Telegram gives you a convenient chat interface while the USB agent is running. It does not make the agent permanently online. If the computer sleeps, the launcher closes, the gateway stops, or the drive is removed, the bot cannot process new requests.

1. Create a Bot with BotFather

Open Telegram and start a chat with the verified @BotFather account. Send /newbot, choose a display name and an available username, then securely record the bot token. Treat this token like a password because anyone who obtains it may be able to control the bot connection.

2. Find Your Numeric Telegram User ID

Hermes supports an explicit user allowlist. Obtain your numeric Telegram user ID using a reputable ID bot or Telegram API method. Do not confuse a username such as @example with the numeric ID required by the allowlist.

3. Run the Hermes Gateway Setup

Start the portable launcher, then run:

Enter the Telegram bot token and your allowed numeric user ID. The relevant official variables are TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS. Confirm that they are saved in the active portable Hermes home.

4. Start the Gateway and Send a Test Message

Foreground mode is useful for a portable setup because you can see errors and stop the gateway before ejecting the drive. Open the bot in Telegram, press Start, and send a simple prompt. If the agent does not respond, verify the token, allowlist, provider key, internet connection, and gateway logs.

Protect Your Agent

Security Rules for a USB-Based AI Agent

A portable agent can contain much more than software. Its data may reveal private conversations, client details, project paths, personal preferences, web activity, Telegram credentials, API keys, OAuth tokens, and tool permissions. Losing an unencrypted drive can therefore be similar to losing an unlocked account vault.

Encrypt Sensitive Data

Use full-drive encryption or an encrypted container. BitLocker To Go is convenient for Windows-centered workflows. LUKS is strong for Linux-only setups. An encrypted APFS volume is appropriate for macOS-only use. A carefully configured VeraCrypt container can be useful across systems where its software is available. Choose the method based on the hosts you control, and test recovery before trusting it with the only copy of your agent.

Never Plug the Drive Into an Untrusted Computer

Encryption protects a drive while it is locked. After you unlock it on a compromised computer, malware can read files, capture credentials, alter launcher scripts, or steal API keys. Public computers, borrowed devices, hotel business centers, and unknown repair-shop systems are not safe execution environments for an agent that has tool access.

Use Dedicated, Limited Credentials

• Create a separate model-provider key for the USB profile.
• Set provider spending alerts, hard limits, and rate limits where available.
• Restrict Telegram access with TELEGRAM_ALLOWED_USERS.
• Do not reuse the same bot token across simultaneously running profiles.
• Avoid placing unrelated SSH keys, cloud-admin credentials, or master passwords on the drive.
• Rotate every credential immediately if the USB is lost or copied.

Keep Command Approvals Enabled

Hermes can use terminal and automation tools. Review dangerous commands instead of enabling an unrestricted approval-bypass mode. A portable agent encounters different computers and directory layouts, so a command that was harmless on one system may target the wrong location on another.

Back Up the Portable Home

Hermes supports backup and profile export workflows, and you can also copy the portable directory while all Hermes processes are stopped. Maintain at least one encrypted backup away from the USB. A backup protects you from flash wear, accidental formatting, corruption, theft, and launcher mistakes.

Make It Dependable

Performance and Reliability Tips

Prefer an External SSD for Heavy Use

A quality flash drive is adequate for light sessions and configuration portability. An external SSD offers much faster random reads and writes, better sustained performance, and usually better endurance. This matters when the agent accumulates many sessions, browser artifacts, tool caches, logs, package files, or local model data.

Keep the Runtime Local and the State Portable

The most maintainable design installs Hermes and dependencies on each trusted host but stores the profile on the USB. It avoids carrying multiple Python environments, Node installations, browser binaries, and OS-specific executables. It also allows each host to use the correct architecture, such as x86-64 or ARM64.

Avoid Running Large Local Models From a Basic USB Stick

Local model files can be tens or hundreds of gigabytes, and inference repeatedly reads substantial data. A slow drive can make model loading painful, while the host still needs sufficient RAM or GPU memory. If offline inference is your goal, use a fast external NVMe SSD and a computer designed to run the chosen model. The portable Hermes state can remain separate from the much larger model files.

Control Logs and Caches

Review the logs, browser screenshots, media caches, checkpoints, and temporary files periodically. Do not delete active databases or unknown files while Hermes is running. Create a backup first, then use Hermes commands or documented cleanup methods where possible.

Keep a Simple Recovery File

Add a nonsecret README-FIRST.txt that records the expected folder layout, official installation links, commands to set HERMES_HOME, and the date of the last successful backup. Do not put API keys, encryption recovery keys, or Telegram tokens in that file.

Fix Common Problems

Troubleshooting a Portable Hermes USB Agent

The Launcher Works on One PC but Not Another

The second computer may not have Hermes on its PATH, or it may be missing Python, Git Bash, Node.js, ffmpeg, ripgrep, Chromium, or another optional dependency. Run hermes --version and hermes doctor outside the launcher. Install Hermes using the official instructions for that operating system.

Windows Assigned a Different Drive Letter

Replace hard-coded paths such as E:\hermes-data with a launcher that calculates the USB root from $PSScriptRoot. Relative path discovery is one of the most important parts of a genuinely portable Windows setup.

Hermes Starts With a Blank Configuration

Print the value of HERMES_HOME before launching Hermes. Confirm that it points to the correct mounted folder and that config.yaml and .env are present there. You may have run the setup wizard before setting the variable, causing files to be written to the host’s default Hermes directory.

The API Key Appears to Be Missing

Check the active portable .env, not the computer’s normal Hermes directory. Re-run hermes model or use hermes config set while the correct HERMES_HOME is active. Never paste the full key into screenshots, support tickets, or public logs.

The Shell Script Says Permission Denied

On Linux or macOS, grant execution permission with chmod +x. On exFAT, Unix execution permissions may not persist in the same way they do on ext4 or APFS. You can always invoke the script explicitly with bash path/to/start-hermes-linux.sh after inspecting it.

Paths With Spaces Break a Command

Quote every calculated path. Both example launchers above preserve spaces in the USB label and folder names. Avoid manually concatenating commands without quotes.

Telegram Does Not Respond

Confirm that the portable gateway is running, the bot token is valid, your numeric ID is in the allowlist, and the provider key has credits. Review gateway logs inside the portable Hermes home. Another running instance may also be using the same bot token.

Antivirus Blocks the Launcher

Do not immediately disable security software. Inspect the script, verify its source, scan the drive, and compare every network download with the official project. A custom menu script may trigger heuristic detection, but that is not proof that it is safe.

Files Become Corrupted After Moving the Drive

Stop Hermes and the gateway before unplugging. Use the operating system’s safe-eject function. Check the drive for file-system errors, restore from a known-good backup, and consider moving heavy use to an external SSD or a journaled native file system.

It Works on Intel but Not Apple Silicon or ARM Linux

A bundled binary or virtual environment was probably built for a different CPU architecture. Install Hermes natively on that host and reuse only the portable data directory, or maintain separate runtime directories for each operating system and architecture.

The Agent Is Too Slow

Test drive speed, reduce unnecessary caches, use a faster model, and keep large runtimes or local models on faster storage. Cloud-model response speed also depends on internet latency and provider capacity, which a faster USB cannot improve.

Questions Answered

Frequently Asked Questions

Final Recommendation

Is a Portable USB AI Agent Worth Building?

Yes, when your goal is to carry one consistent Hermes workspace between trusted computers. It is useful for demonstrations, travel, workshops, private local profiles, and situations where you want physical custody of the agent’s files. Hermes’ supported HERMES_HOME override makes the data-directory portion straightforward.

The design is not a replacement for a server. A removable drive can be lost, damaged, or unplugged; it cannot answer Telegram while every host is off; and cross-platform portability still requires operating-system-specific runtime support. Treat the USB as a secure portable workspace, maintain encrypted backups, use limited credentials, and keep the launchers simple.

When continuous availability matters, deploy a separate Hermes instance on a VPS. That gives scheduled jobs, messaging gateways, and long-running tools a stable home while your USB profile remains available for portable local work.