How to Run Hermes Agent on AWS with Persistent Volumes

According to the 2025 CNCF Annual Cloud Native Survey, 79% of developers now run stateful workloads in containers [CNCF Annual Cloud Native Survey 2025]. However, typical deployment templates for AI agents treat container runtimes as entirely stateless. When you deploy the Nous Research Hermes Agent in a cloud environment, treating its storage as ephemeral leads to immediate data loss. The agent stores its configuration files, SQLite databases, and dynamically learned skills in the user's home directory. In a standard setup, this directory defaults to ~/.hermes, which maps to /opt/data inside the official Docker image [Nous Research Hermes Agent GitHub Repository].

When a container orchestrator like Amazon ECS restarts a task or scales a service, the underlying container is terminated. If the container uses ephemeral storage, the restart destroys all local files. The agent loses its configuration, history, and any skills it has learned. It must start over, which breaks its ability to execute long-running tasks or retain context across sessions.

Deploying Hermes Agent on AWS requires a persistent storage solution. This guide details how to configure Amazon EFS to store the agent's persistent directory. This setup ensures that your agent retains its memory and skills even if the container restarts.

When configuring persistent storage on AWS, developers typically choose between Amazon EBS and Amazon EFS. Selecting the right storage backend depends on how you plan to scale your agent operations.

Amazon EBS Amazon Elastic Block Store provides low-latency block storage. However, EBS volumes can only be attached to a single EC2 instance at a time. If your agent is running in an ECS task and the task rescheduled to a different Availability Zone, the EBS volume must be detached from the old host and re-attached to the new one. This process causes task startup delays. Furthermore, EBS does not allow concurrent access from multiple tasks, preventing you from scaling out your agent workforce.

Amazon EFS Amazon Elastic File System provides a managed network file system that supports concurrent read-write access. This allows multiple containers to access the same storage volume simultaneously, even across different Availability Zones. EFS supports the NFSv4 protocol and automatically scales its capacity as files are added. Using EFS for the ~/.hermes folder ensures that your agent can read and write its skills and databases without lock contention or scaling limitations.

VPC and Network Setup To deploy EFS, you must create a file system in your Virtual Private Cloud. Ensure that you configure mount targets in every subnet where your container tasks will run. The network configuration requires setting up security groups to allow traffic. This configuration relies on the hermes agent docker efs integration, where EFS acts as the shared storage target for your containers.

Security Group Rules The security group attached to your EFS mount targets must allow inbound TCP traffic on port 2049, which is the standard NFS port [AWS Elastic File System Documentation]. You should configure the source of this inbound rule to be the security group assigned to your ECS containers. This configuration prevents unauthorized access to the network share while allowing your containers to connect.

EFS Access Points To manage permissions, create an EFS Access Point. Access Points allow you to override the user ID and group ID of the client connecting to the file system. In the Access Point settings, configure the POSIX user configuration with a User ID of 1000 and a Group ID of 1000. You can also configure the root directory creation permissions to ensure that the persistent folder is initialized with the correct ownership when first mounted.

With your EFS file system and access point configured, the next step is mounting the volume in your ECS task definition. This step-by-step process connects the persistent network share to the /opt/data directory inside your container.

Step 1: Declare the Volume Open your ECS task definition template. In the volumes section, add an entry for your EFS file system. You must specify the File System ID and the Access Point ID to route traffic to the correct subdirectory.

Step 2: Configure the Container Mount Point In the container definitions section, find the definition for your Hermes Agent container. Add a mount point configuration that maps the declared volume to the container path.

Here is a task definition JSON configuration showing the volume and mount points:

{
  "volumes": [
    {
      "name": "hermes-persistent-storage",
      "efsVolumeConfiguration": {
        "fileSystemId": "fs-0a1b2c3d4e5f6g7h8",
        "rootDirectory": "/",
        "transitEncryption": "ENABLED",
        "authorizationConfig": {
          "accessPointId": "fsap-0z1y2x3w4v5u6t7s8",
          "iam": "ENABLED"
        }
      }
    }
  ],
  "containerDefinitions": [
    {
      "name": "hermes-agent",
      "image": "nousresearch/hermes-agent:latest",
      "essential": true,
      "environment": [
        {
          "name": "HERMES_UID",
          "value": "1000"
        },
        {
          "name": "HERMES_GID",
          "value": "1000"
        }
      ],
      "mountPoints": [
        {
          "sourceVolume": "hermes-persistent-storage",
          "containerPath": "/opt/data",
          "readOnly": false
        }
      ]
    }
  ]
}

Step 3: Set User Permissions The Nous Research Hermes Agent entrypoint script reads the HERMES_UID and HERMES_GID environment variables [Nous Research Hermes Agent GitHub Repository]. The script adjusts file ownership in /opt/data before running the main process. By setting these variables in your task definition, you match the owner configuration of your EFS Access Point to avoid access denied errors when the container starts.

Persist Hermes Agent databases and skills securely

Create a shared cloud workspace with built-in versioning, automated metadata extraction, and a dedicated MCP server interface for your running agent. Starts with a 14-day free trial.

Start 14-Day Trial

Deploying Hermes Agent on AWS with Amazon EFS ensures that the agent's internal memory and skills survive container lifecycles. However, managing the files that your agent creates remains a challenge for teams. When the agent operates in an isolated VPC subnet, human team members cannot easily view its outputs, review its edits, or supply it with new context documents.

S3 and Bucket Policies Developers sometimes write scripts to sync container files to Amazon S3 buckets. While S3 provides highly durable object storage, it is not designed for real-time collaboration. Your team must manage IAM roles, configure bucket policies, and write custom code to handle file updates. S3 lacks version histories for concurrent edits and does not provide collaborative editors.

Google Drive Limits Using standard cloud drives like Google Drive creates silos. These platforms are built for human users, making it difficult for agents to connect without complex OAuth flows or fragile API integrations.

Fast.io Workspaces To bridge the gap, teams can connect their agents to Fast.io workspaces. Fast.io is an intelligent workspace platform that hosts files for both human teams and AI agents. By running the Fast.io MCP server, your running agent can read and write files directly within your team's folders.

The platform supports MCP-native access via Streamable HTTP at /mcp or legacy Server-Sent Events at /sse. The documentation at mcp.fast.io/skill.md outlines the toolset. Instead of writing custom AWS integration code, you configure your agent to connect to the MCP server.

Every file uploaded to the workspace benefits from automated versioning. If your agent edits a configuration file or a script, the platform stores a complete version history. If an agent's change breaks a configuration, you can review the diffs and restore a previous version from the dashboard. This setup ensures that agent modifications remain auditable and secure.

Once your agent has access to a Fast.io workspace, you can enable Intelligence Mode. Intelligence Mode auto-indexes documents in the background, allowing the agent to perform hybrid search. This search combines full-text and semantic queries to find files, returning direct citations.

If the agent needs to parse structured details from documents, you can use Metadata Views. This capability turns files into a filterable database.

Natural Language Schemas You define the fields you want to extract using plain text instructions. The platform supports Text, Integer, Decimal, Boolean, URL, JSON, and Date & Time fields.

Document Processing The platform parses incoming files and populates a spreadsheet view. No templates or OCR rules are required. Agents can create these views and query the extracted data via MCP, letting them process files programmatically. For more details, visit the Metadata Views page.

Webhooks and Cloud Import To trigger external actions, you can configure webhooks that alert your systems when files change. If your team has documents in other platforms, the URL Import feature pulls files from Google Drive, OneDrive, Box, or Dropbox via OAuth without using your agent's local bandwidth.

Handoff and Pricing Managing these intelligent workspaces requires a paid subscription. Fast.io offers plans tailored to different team sizes on the 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.

The workspace configuration allows an agent to register a user account for free. Once the agent builds the initial workspace structure, it can transfer administrative ownership to a human. This handoff gives billing control to the human while letting the agent retain admin access to continue running its tasks in the background.