How to Run Hermes Agent on Modal with Persistent Files

Modal containers scale to zero and shut down completely after an idle period of less than 5 minutes, which destroys any files written directly to the container's local file system [Modal Sandbox Documentation]. This short timeout creates a persistence challenge for Nous Research Hermes Agent. To solve this, developers must configure the environment to run hermes agent on modal with persistent files, ensuring that settings and memory remain intact across sleep-and-wake cycles.

When running Nous Research Hermes Agent as a serverless container on Modal, the agent code executes in response to incoming requests. If there are no requests for 5 minutes, Modal reclaims the container's resources. When the container sleeps, any local changes made to the /root/.hermes/ directory disappear. When a new request triggers a wake-up, the agent starts from a blank state. It has lost its settings, its API keys, its history, and its custom skills.

To build a persistent system, you must preserve the contents of the ~/.hermes/ directory. This folder contains the state.db SQLite database, which is the heart of the agent's memory. It also holds the active agent profiles, configuration YAML files, secret environment files, and custom skills developed by the agent during its runs.

Using Modal's persistent volumes solves this problem. These volumes act as network-attached disks that survive container sleep-and-wake cycles. Because these volumes mount with sub-millisecond latencies, they do not slow down the agent's execution or add noticeable overhead during database reads and writes [Modal Volumes Performance Guide]. By mapping this persistent volume to the container's home directory, the agent maintains its memory across runs. This guide will show you how to configure this setup.

To mount a volume to your agent, you define the volume in your python script and pass it to the function decorator. Below is the configuration to run Hermes Agent on Modal with persistent files.

import os
import modal

app = modal.App("hermes-agent-app")

hermes_volume = modal.Volume.from_name("hermes-agent-data", create_if_missing=True)

image = (
    modal.Image.debian_slim()
    .pip_install("hermes-agent")
)

@app.function(
    image=image,
    volumes={"/root/.hermes": hermes_volume},
    timeout=600
)
def run_agent_task(prompt: str):
    hermes_volume.reload()
    
    os.environ["HERMES_HOME"] = "/root/.hermes"
    
    from hermes_cli.runner import execute_agent
    
    result = execute_agent(prompt)
    
    hermes_volume.commit()
    
    return result

This configuration achieves the necessary persistence. The code maps the hermes-agent-data volume to the /root/.hermes folder inside the container.

The configuration requires two critical operational commands:

1. hermes_volume.reload(): Because Modal volumes use distributed replication, different container instances might write to the volume at different times. Running a reload before executing the agent pulls the most recent files from the underlying storage.
2. hermes_volume.commit(): The volume caches writes within the container. If you do not call commit at the end of the run, modifications to the SQLite database and skill directories will not save to the shared disk before the container sleeps.

This structured setup ensures that your hermes agent modal deployment is both cost-effective and stateful. The container runs only when needed, but it never forgets its context.

Here is the step-by-step setup sequence for the persistent volume:

1. Initialize the persistent volume using modal.Volume.from_name("hermes-agent-data", create_if_missing=True).
2. Map the volume to the container path /root/.hermes in your @app.function decorator's volumes dictionary.
3. Define the HERMES_HOME environment variable inside your function to point to /root/.hermes.
4. Run hermes_volume.reload() before executing the agent to pull the latest configuration.
5. Execute the agent task and then call hermes_volume.commit() to persist updates.

Once the volume is mounted, the agent writes all its configuration and memory files to the persistent store. The core file is state.db, an SQLite database that stores your agent's history and active sessions. Because SQLite handles concurrent reads well, the agent can quickly retrieve context. However, concurrent writes from multiple active containers can lead to database lock errors.

To avoid lock conflicts in your modal persistent volume hermes setup, you must isolate execution paths. Nous Research Hermes Agent supports multiple profiles. Each profile is a subdirectory under /root/.hermes/profiles/ with its own config.yaml and .env files. If you run multiple tasks concurrently, you should configure the agent to use distinct profiles.

You can initialize a profile by running hermes profile create <profile_name> during your container build or within your startup script. To switch profiles in python, set the active profile before running the executor:

os.environ["HERMES_PROFILE"] = "work"

This configuration isolates the settings, skills, and databases for each task. The agent's custom skills are stored in /root/.hermes/skills/, and they remain accessible only to the active profile. This isolation prevents concurrent execution instances from writing to the same database file, avoiding state corruption in serverless environments.

Additionally, sensitive variables like API keys should not be hardcoded in your config.yaml. Instead, configure them as Modal Secrets and pass them into the container environment. The agent automatically reads these secrets from its environment variables, keeping your configuration files clean and portable.

While persistent volumes are suitable for internal agent files like configuration files and SQLite databases, they are not designed for team file collaboration or human review. Storing output files on a raw Modal volume creates access bottlenecks. Humans cannot easily browse, edit, or search these files without running custom scripts or web dashboards.

Developers often rely on standard alternatives for output storage:

1. Local disk storage: This works during local development but fails in cloud-native serverless deployments where files must span multiple instances.
2. Cloud object storage (like Amazon S3): While durable, S3 requires custom interface development, lacks native file versioning tracking for teams, and does not index documents for search automatically.

Fast.io provides a dedicated workspace layer that resolves these bottlenecks. By pointing your agent to write its output files to a Fast.io workspace, you bridge the gap between serverless execution and human teams.

Fast.io offers shared org-owned workspaces where humans and agents collaborate on the same file structure. Every file uploaded or modified by the agent maintains a complete, per-file version history. If an agent writes a file and a human edits it, the entire edit sequence is preserved, making concurrent work auditable and reversible.

Fast.io also features Intelligence Mode, which automatically indexes workspace files for semantic search and retrieval-augmented generation (RAG) with citations. This eliminates the need to configure separate vector databases or build custom RAG pipelines. If the agent needs to extract structured data from documents (like invoices, contracts, or media files), developers can use Metadata Views to turn files into a live, queryable database by describing the fields in natural language Metadata Views Guide.

Agents interact with these workspaces using the Fast.io MCP server, which exposes tools for workspace, storage, and workflow operations. You can connect your agent via the streamable HTTP endpoint at /mcp or the legacy SSE at /sse. The MCP documentation at mcp.fast.io/skill.md outlines the tool surface, while fast.io/llms.txt helps onboard the agent with workspace configurations.

This architecture decouples execution from storage: Modal manages the transient compute and internal databases, while Fast.io hosts the files, indexes them for search, and manages human collaboration.

Managing these workflows requires a paid organization account. Fast.io offers plans tailored to different needs on our pricing page. The Starter plan is $29/mo, and the Business plan is $99/mo. Larger teams can choose the Growth plan at $299/mo. Every organization starts with a 14-day free trial that requires a credit card to activate. The setup process allows an agent to register a free user account and build the workspace, before handing off administrative ownership to a human team member. This handoff transfers billing control while letting the agent retain access to continue its background tasks.

Store and version your Hermes Agent workspace files

Set up a shared workspace with Intelligence Mode, per-file version history, and a consolidated MCP toolset. Get started with a 14-day free trial.

Start 14-Day Trial

Running a stateful system on serverless hardware exposes specific failure points that do not occur on a dedicated server. When you run hermes agent on modal with persistent files, the most common issue is a database lock error. Because Modal scales horizontally, two webhook events can launch two containers that mount the same volume. If both try to write to state.db concurrently, SQLite will fail with a locked error.

To resolve this issue, configure your Modal app to limit concurrency for functions that write to the database. By setting concurrency_limit=1 in the @app.function decorator, you force Modal to process requests sequentially on a single container instance, avoiding database conflicts.

Another common challenge is package installation latency. If you install dependencies during container start, your cold start times will increase. You can resolve this by pre-building your container image with all required Python packages. Use the Modal image builder to run pip installations during the build phase:

image = (
    modal.Image.debian_slim()
    .pip_install("hermes-agent", "pydantic", "openai")
)

This pre-builds the dependencies into the container layer, reducing container start times to milliseconds.

If you encounter authentication errors during deployment, check your credentials. Modal requires active token settings to access remote volumes. You can verify your setup by running modal config show in your terminal. If the token is expired or invalid, run modal token new to re-authenticate, or set the credentials in your execution environment using the MODAL_TOKEN_ID and MODAL_TOKEN_SECRET environment variables.

By combining Modal's serverless compute and persistent volumes for internal memory, and using Fast.io workspaces for shared files and human collaboration, you build a stateful, cost-effective AI system that grows with your team.