How to Run Hermes Agent on a Home Server Without Losing Data

Quick Answer

To run Hermes Agent on a home server without losing data, do not rely on the container’s internal filesystem as the only place where configuration, skills, logs, generated files, or gateway settings live. Plan a persistent host folder or Docker volume first, mount it into the container path the app actually uses, check file ownership, and verify the data still exists after restart or reconfiguration. This article focuses on the common failure pattern where a container cannot find a folder because of volume mount, permission, or path mapping issues.

The safest beginner workflow is:

1. Identify which Hermes Agent data must survive.
2. Choose a dedicated host folder or Docker-managed volume.
3. Map that storage to the correct container path.
4. Confirm the app user can write to it.
5. Back up important configuration before updates or rebuilds.
6. Restart and verify that config, logs, generated files, and gateway settings are still present.

A running container does not automatically mean your data is safe. Data is safe only when it is stored in a persistent location, writable by the correct user, backed up when needed, and validated after restart.

Why Hermes Agent Data Can Disappear in a Container Setup

Containerized apps are often easy to start and easy to replace. That is useful for updates, testing, and recovery, but it also means anything stored only inside the disposable container layer may be lost when the container is removed, recreated, or rebuilt.

For a self-hosted AI agent, this can affect more than basic settings. Depending on how you use the agent, you may care about model configuration, skills, generated files, logs, messaging gateway settings, and other app state.

Container Restarts vs Persistent App Data

A normal container restart does not always remove data. If the data is stored in a persistent volume or correctly mapped host folder, it should remain available after restart.

The risk appears when important files live only inside the container’s writable layer. That layer is not the same as a planned persistent data location. If you recreate the container without preserving or remounting the right path, the app may start fresh or fail to find its previous files.

Why Deleting or Recreating a Container Can Remove Unsaved State

Deleting or recreating a container is different from restarting it. A recreated container may use a new internal filesystem, new environment variables, or a different mount mapping.

If Hermes Agent settings, skills, logs, or generated outputs were never written to a persistent host folder or volume, they may not follow the new container. This is why “the app worked yesterday” and “the app reset after update” can both be true.

The safe habit is to treat container replacement as a data-risk event unless you have confirmed where the app data is stored.

Why Host Paths and Container Paths Must Be Planned First

A host path is where data lives on the home server. A container path is where the app sees that data from inside the container. A volume mount or bind mount connects those two worlds.

If the host path is correct but mounted to the wrong container path, the app may still behave as if the folder does not exist. If the container path is correct but the host path is disposable, the app may write data somewhere you did not intend.

Plan the mapping before you run the app, not after you lose data.

What Data Should You Protect Before Running Hermes Agent?

Before you change a container, update an image, or reconfigure a gateway, list the data that would be painful to recreate. Not every file needs the same protection, but you should know which files are critical.

A useful rule is: protect anything that stores identity, access, configuration, learned workflow, or output you cannot easily regenerate.

Agent Configuration and Model Provider Settings

Model settings usually include provider choice, endpoint values, model names, context-related options, and API access. If these settings are lost, the agent may start but fail to answer correctly.

Store model configuration in a persistent app data path, not in a throwaway shell session. If configuration is provided through environment variables, keep a safe copy of the compose file, env file, or deployment notes.

Also protect any setup choices that determine how the agent uses terminal tools or messaging gateways.

App Memory, Sessions, Skills, and Runtime State

Hermes Agent data can include more than one configuration file. The Hermes skills data structure explains that skills live in ~/.hermes/skills/, which is the primary source of truth for bundled, hub-installed, and agent-created skills. It also describes related state such as bundled manifests, skill bundles, hub tap configuration, pending skill writes, and config settings.

This matters because agent-created skills can become reusable procedural memory. If the wrong path is mounted, you may lose not only settings but also workflows the agent learned or skills you installed.

Treat skills, bundles, pending writes, and profile-related state as persistent agent data.

Downloads, Generated Files, Logs, and Tool Outputs

Generated files are easy to overlook. An agent may create plans, scripts, reports, screenshots, logs, or downloaded files during normal use.

These files may be saved in the active workspace, backend working directory, app home directory, or a mounted output path. If that location is inside the container only, the files may disappear when the container is removed.

For practical use, decide where generated files should appear on the host server and verify that the container writes there.

API Keys, Bot Tokens, and Environment Variables

Secrets are not ordinary app data. API keys, bot tokens, dashboard passwords, and environment variables need both persistence and protection.

Do not save secrets in random generated output folders or broad shared directories. Keep them in a controlled configuration path with limited access.

A good secret-handling setup should answer:

• where the secret is stored;
• which user can read it;
• whether it is included in backups;
• whether the backup is encrypted or access-controlled;
• how the secret can be rotated if exposed.

Host Path vs Container Path vs Volume Mounts

This is the key concept behind most “container cannot find folder” and “data disappeared after restart” problems. A container can only see what exists inside its own filesystem or what has been mounted into it.

Use The Agent Data Survival Map to organize the setup before you troubleshoot.

Framework Module	Key Question	What It Helps You Decide	Setup / Troubleshooting Focus
Data Inventory	What data must survive container restart or recreation?	Which configs, skills, logs, downloads, tokens, and generated files need protection	Prevents treating important agent data as disposable state
Persistence Path	Where should persistent data live on the host?	Whether to use a dedicated host folder, Docker volume, or bind mount	Prevents data reset after container recreation
Mount Mapping	Is the host path correctly mapped into the container path?	Whether the app can actually see the intended folder	Helps diagnose missing folder and wrong destination path errors
Permission Boundary	Which user owns the mounted data and which user writes to it?	Whether host user, container user, app user, or root owns the files	Helps fix permission denied without making everything root-owned
Backup Boundary	What should be backed up before updates or reconfiguration?	Which data is critical and which data is temporary	Prevents losing config, skills, sessions, tokens, and gateway settings
Restart Validation	Does the data still exist after restart or update?	Whether setup is actually durable	Turns “it runs” into a repeatable safety check

What the Host Server Stores

The host server stores the real folders, disks, and Docker-managed storage locations. If you use a bind mount, you choose a specific host folder. If you use a named Docker volume, Docker chooses and manages the storage location.

This distinction matters because host visibility affects backup and migration. A bind-mounted folder may be easier for a beginner to locate and copy. A named volume may be cleaner for Docker-managed app data, but you still need to know how to inspect or back it up.

Choose the storage style based on whether you need human-readable host folders, Docker-managed app persistence, or a controlled backup path.

What the Container Can See

The container sees its own internal filesystem and any mounted paths. It does not automatically see every folder on your home server.

Docker’s bind mount walkthrough shows how a host directory can appear inside a container at a target path, and how file changes can be reflected between the host and the container when the mount is correct.

That is the core idea: the app does not care where a file exists on the host unless the file is mounted into the path the app uses.

How Volume Mounts Keep App Data Persistent

A persistent mount gives the app a stable place to write data beyond the life of a single container. For app data, this is often the difference between “restart-safe” and “container-lifetime only.”

The mount must match the app’s expected data path. If the app writes to one internal folder but you mount a different folder, the data may still go into disposable storage.

A good persistent setup should define:

• the host folder or named volume;
• the container target path;
• whether the mount is read-write or read-only;
• which app data belongs there;
• how the path will be backed up.

Why Wrong Path Mapping Causes Missing Folder Errors

Wrong mapping often looks like a missing folder problem. The folder may exist on the host, but the container cannot see it. Or the container may have a folder at the expected path, but it is not connected to the host folder you intended.

Common symptoms include:

• the app says a folder does not exist;
• generated files appear inside the container but not on the host;
• logs disappear after rebuilding the container;
• config resets after update;
• you edit a host folder but the app keeps using old settings;
• backup scripts run but do not include the real app data.

When this happens, check host path and container path together. Do not inspect only one side.

How to Run Hermes Agent Without Losing Data

The goal is not just to start Hermes Agent. The goal is to make sure the data you care about survives restart, update, rebuild, and reconfiguration.

Step 1: Choose a Dedicated Host Data Folder

Choose a host data folder before running or rebuilding the container. It should be easy to identify, easy to back up, and not mixed with unrelated personal files.

A dedicated folder reduces risk because you can see what belongs to the app. It also avoids mounting your entire home directory or other sensitive folders into the container.

A practical host data folder should be:

• specific to the app;
• outside disposable download paths;
• included in your backup plan;
• not shared broadly with unrelated services;
• writable only by the users or services that need access.

Step 2: Mount the Data Folder Into the Container

Mount the host data folder into the container path the app expects. This is the moment where many data-loss issues are created or prevented.

For a bind mount, the host path is chosen by you and the target path is where it appears inside the container. For a named volume, Docker manages the host-side location.

Do not assume the app will automatically use a mounted folder. Confirm that the mounted target matches the actual app data path.

Step 3: Confirm the Container Uses the Expected App Data Path

After mounting, check the path from inside the container. A folder can exist on the host and still be invisible to the app if it is not mounted correctly.

The simplest validation is to create or locate a harmless test file from one side and confirm it appears on the other side. Then verify that the app writes real config, logs, or generated files into the same persistent path.

This step is especially important before updates or migration.

Step 4: Check File Ownership and Write Permissions

A correct mount can still fail if the app cannot write to it. Permission errors often happen when files are created by root but the app later runs as a different user.

Check ownership before changing permissions broadly. The right fix is usually to make the intended app user able to read and write the specific app data folder, not to give every process full control over broad host directories.

If you see permission denied, identify:

1. the mounted host path;
2. the container target path;
3. the user running the app;
4. the file owner;
5. whether the mount is read-only;
6. whether a backup or export path is also writable.

Step 5: Keep Secrets and Config Files Outside Disposable Paths

Secrets and config files should not live only in temporary folders, generated output directories, or ad hoc shell history. If you use environment variables, keep the deployment file or env file in a controlled persistent location.

Avoid mixing secrets with logs or generated artifacts. Logs may be shared for troubleshooting, while secrets should never be shared casually.

If you back up secrets, protect the backup. A backup that exposes API keys or bot tokens creates a different kind of risk.

Step 6: Restart the Container and Verify Data Still Exists

After setup, restart the container and check whether the important data remains. This is the most practical test of persistence.

Do not stop at “the container starts.” Confirm that:

• model settings still exist;
• skills or app state remain visible;
• logs continue in the expected place;
• generated files appear on the host;
• gateway or bot settings still work;
• backup files can be located.

A setup that passes restart validation is much safer than one that only passed the first install.

Permissions, Backups, and Safety Boundaries

Data safety depends on three boundaries: who can write, what is backed up, and what the agent is allowed to touch. These boundaries are especially important for self-hosted agents because they may create files, modify workflows, or interact with tools.

Why Container User Permissions Matter

Container user permissions decide whether the app can read and write its data. If the app runs as one user but the mounted folder is owned by another user, write operations may fail.

This is why running a setup command as root can create a later problem. Root may successfully create files, but the normal app user may not be able to modify them.

Fix permissions at the app data folder level. Avoid broad permission changes that expose unrelated host files.

Why You Should Avoid Running Everything as Root

Root can bypass many restrictions, but that does not make it a safe default. Running everything as root can create root-owned files, hide permission problems, and give the app more access than it needs.

For most self-hosted app workflows, root should be used only for specific administrative steps. Routine app configuration should run as the intended app or container user when possible.

A safer pattern is least privilege: give the app write access only to the folders it needs.

When to Use Read-Only Mounts or Limited Folders

Use read-only mounts when the agent needs to inspect files but should not modify them. Use limited writable folders when the agent needs to create outputs but should not touch broad personal or system directories.

This is especially useful when you want the agent to generate reports, plans, or scripts without giving it write access to all server files.

A limited-folder design reduces the impact of mistakes. It also makes backups easier because you know which folder contains app state and which folder contains generated outputs.

How to Back Up Agent Data Before Updates or Reconfiguration

Back up important app data before changing container images, mount paths, gateway settings, or profiles. A backup is useful only if you know what it includes and how to restore it.

The Docker community volume backup permission discussion shows a common user-facing failure pattern: a path may exist, but backup or write operations can still fail because of permission, ownership, labeling, or mount-related restrictions.

Use that as a reminder to test backups, not just create them. A backup plan should include both backup creation and restore verification.

Common Problems and How to Fix Them

When Hermes Agent data is missing, do not immediately reinstall the app. First identify which layer failed: data inventory, persistence path, mount mapping, permission boundary, backup boundary, or restart validation.

The Container Cannot Find a Mounted Folder

This usually means the path exists in one layer but not the other. The host folder may not be mounted, the container target path may be wrong, or the app may be looking somewhere else.

Check in this order:

1. Confirm the folder exists on the host.
2. Confirm the container has the mount.
3. Confirm the target path inside the container.
4. Confirm the app is configured to use that target path.
5. Confirm the app user can read the folder.
6. Confirm the mount was recreated after changing compose or run settings.

Do not fix this by creating random folders inside the container. That may make the error disappear temporarily while leaving data in disposable storage.

App Data Resets After Restart

If data resets after restart, the app may be writing to the container’s internal filesystem instead of the persistent path. It may also be using a different profile, environment variable, or data directory than expected.

Check whether the data path before restart and after restart are the same. Then check whether the folder is backed by a mount or only by the container layer.

If the app was recreated, confirm the same volume or bind mount was attached to the new container.

Permission Denied Errors in the Data Directory

Permission denied means the app can see the path but cannot perform the required action. The issue may be ownership, read-only mount settings, filesystem labels, or a mismatch between host user and container user.

Start with the smallest check: can the app user create a harmless test file in the data directory? If not, inspect the owner and mode of that specific path.

Avoid solving this by giving broad write access to the entire host directory. Fix the app data path and the intended app user.

Generated Files Are Saved Inside the Container Only

If generated files disappear after rebuild, they were probably saved inside the container instead of a mounted host path. This often happens when the app’s working directory or output directory is not mapped.

Decide where generated files should land. Then mount that output folder or configure the app to write to an existing persistent location.

After changing the path, generate a harmless test file and confirm it appears on the host.

Bot or Gateway Settings Disappear After Reconfiguration

Gateway settings may disappear if configuration is stored in a non-persistent path or if the app runs under a different profile after restart. The same can happen if an environment variable is changed in one place but the running container uses another value.

Check whether the gateway config, bot token reference, allowlist, and dashboard settings are stored in the expected persistent location. Then restart the gateway and confirm the settings remain active.

If the bot works before restart but not after restart, focus on persistence and environment configuration before changing the token.

How to Check Whether Your Hermes Agent Data Is Safe

A safe setup should pass restart, write, backup, and access checks. These checks do not need to be complicated, but they should be repeated after major changes.

Config Persists After Restart

Change a harmless setting, restart the container, and verify that the setting remains. This confirms that the app is writing to persistent storage.

If the setting disappears, do not continue adding more configuration. Fix the data path first.

Logs and Generated Files Appear in the Expected Host Folder

Logs and generated files should appear where you expect them on the host. If they only appear inside the container, they may be lost during rebuild.

Check both sides of the mount. The host and container should agree about the files that matter.

The Agent Can Write to App Data Without Permission Errors

The agent should be able to write to its app data folder as the intended user. A successful write test is more useful than simply confirming that the folder exists.

Watch for permission errors in logs after restart. Some permission problems appear only when the agent tries to update config, write a skill, save a generated file, or update gateway state.

Backup Files Can Be Located and Restored

A backup is incomplete until you can locate it and restore it to a test location. At minimum, confirm that the backup contains the data you intended to protect.

For important setups, restore the backup to a separate folder or test instance before relying on it. This avoids discovering restore problems only after data is lost.

Dashboard or Messaging Access Still Works After Reboot

After reboot, verify that the dashboard or messaging access still works. This confirms that persistent data, credentials, gateway settings, and network access are still aligned.

If the dashboard works but messaging fails, check gateway settings and token access. If messaging works but generated files disappear, check output path and mounts.

How This Works in a Real Home Server Environment

In a real home server setup, the same data-safety logic applies even when the system provides a friendly dashboard. You still need to know which data must survive, where it is stored, how the container sees it, which user can write to it, and how to verify it after restart.

For example, the ZimaOS Hermes Agent setup workflow shows a device-specific path that includes model provider configuration, Telegram gateway setup, entering the Hermes container, activating the app environment, checking the Web Dashboard, and troubleshooting permission or bot response issues.

For users running Docker apps, agent workflows, and local services on a compact always-on machine, ZimaBoard 2 home server is a relevant example of the type of lightweight home server environment where persistent folders, container paths, permissions, and storage expansion need to be planned together. It is not the only possible setup, but it matches the kind of self-hosted app workflow discussed in this guide.

The general lesson is portable: before you trust a containerized agent with useful work, make sure its important data survives beyond the container that happens to be running today.

FAQ

Why did my Hermes Agent data disappear after restarting the container?

A simple restart should not delete persistent data, but the app may appear reset if it was writing to a non-persistent container path. The data may also be missing if the container was recreated without the same volume or bind mount. Check the host path, container path, and actual app data path before changing more settings.

What is the difference between a Docker volume and a bind mount?

A Docker volume is managed by Docker, while a bind mount maps a host folder you choose into the container. A volume is often clean for app-managed data, while a bind mount is easier to locate directly on the host. The best choice depends on whether you want Docker-managed storage or a visible host folder for backup and inspection.

Where should I store Hermes Agent app data on a home server?

Use a dedicated persistent folder or Docker volume rather than a temporary container path. The location should be easy to back up, limited to the app’s needs, and not mixed with sensitive unrelated files. The most important point is that the app’s expected container path must actually map to that persistent storage.

Why does the container say a folder does not exist?

The folder may exist on the host but not inside the container. This usually means the mount was not created, the source path is wrong, the target path is wrong, or the app is looking in a different container path. Check both the host side and the container side instead of creating a new folder blindly.

Should I run Hermes Agent as root to avoid permission errors?

Running as root may hide the immediate error, but it can create root-owned files and increase risk. A safer approach is to make the intended app user able to read and write only the required app data path. Use root only for specific administrative or repair actions when you understand the change.

How often should I back up Hermes Agent data?

Back up before updates, container rebuilds, path changes, gateway reconfiguration, or migration to another server. For active use, schedule regular backups based on how often skills, settings, generated files, or sessions change. A backup is not reliable until you have confirmed that the files can be located and restored.