How to Configure and Manage Hermes Agent Profiles

GitGuardian's State of Secrets Sprawl 2026 report found that developers leaked 28,650,000 secrets in public GitHub repositories in 2025, which represents a 34% year-over-year increase. Leaks of AI service credentials specifically grew by 81% year-over-year to over 1,200,000 leaks. This rapid growth in credential leakage highlights the risks of building AI agents without strict credential boundaries. When developers deploy Nous Research Hermes Agent, they often default to using a single shared home directory. This shared setup mixes API keys, tool configurations, and memory files across work tasks, personal automation, and public messaging bots.

Hermes Agent profiles are independent home directories that isolate configuration, skills, memory, and credentials, allowing you to run multiple specialized agent roles on the same server. By creating dedicated boundaries for different tasks, you avoid credential contamination and prevent unauthorized agents from reading restricted keys. Instead of writing custom permission wrappers or scripting complex setup routines, you can use the built-in profile CLI to manage separate agent identities.

This profile separation is necessary for development teams deploying multiple agent instances. It ensures that an agent running a public Telegram gateway bot has no access to private GitHub tokens, internal databases, or expensive model endpoints. Each profile acts as a complete Hermes directory, providing clean isolation for variables, databases, and local SOUL.md files. You can read more about installing the agent by visiting the official Nous Research GitHub repository page.

A Hermes Agent profile is a complete, self-contained directory that stores all state and parameters required for the agent to run. When you create a profile, Hermes sets up a dedicated directory structure under ~/.hermes/profiles//. This directory isolates the following files for 100% role separation:

config.yaml: This file defines model settings, default terminal parameters, auxiliary LLM endpoints, and tool-specific configurations. Each profile can target a different model provider or run on a local model server without impacting other profiles.

.env: This file isolates profile-specific environment variables, API keys, and messaging platform tokens. If a token is stored in a profile's local .env file, it is completely hidden from other agent instances running on the same host.

SOUL.md: This file defines the agent's personality, goals, behavior guidelines, and operational boundaries. You can write different instructions for a coding assistant and a customer-facing bot, ensuring they never mix their identities.

Sessions and Memory: The sessions folder contains full chat transcripts, while the local state.db database stores persistent memory. This prevents observation leakage and ensures that personal memories do not spill into professional work sessions.

Skills: The skills folder contains custom tools and procedures. You can load specific skills only where they are needed, keeping the agent's active context focused.

The Hermes CLI provides a set of subcommands to create, list, use, describe, and delete profiles. To see details of your active profile, run the show command:

hermes profile show

When you need to create a new profile, you can start from a blank setup or clone files from an existing configuration. To create a blank profile called coder, run the following command:

hermes profile create coder

This creates a fresh directory with default settings. If you want to replicate your current configuration, API keys, and custom skills, use the clone option:

hermes profile create work --clone

For a complete snapshot that copies configuration, memory databases, custom skills, cron tasks, and plugins, use the clone-all option:

hermes profile create backup --clone-all

To select a specific source profile for cloning, use the clone-from option:

hermes profile create work-backup --clone-from coder --clone-all

If you need a lightweight profile without any pre-installed custom tools, add the no-skills option. This writes a marker that prevents automatic updates from seeding the skills directory:

hermes profile create sandbox --no-skills

To see all profiles on your machine, run the list command. The active profile is marked with an asterisk:

hermes profile list

To change the default profile used by your shell, run the use command:

hermes profile use coder

This makes the coder profile sticky, meaning all future hermes commands will target it. If you prefer to specify the profile per command, use the global -p flag. This is the safest approach for cron jobs and automated scripts:

hermes -p coder chat

Every profile also automatically gets a shell command alias at ~/.local/bin/, allowing you to run coder chat or coder setup directly in your terminal. For details on standard agent configuration and discovery, you can read the Fast.io agent onboarding document which guides agent behavior in shared environments. To manage task routing in a multi-agent system, the kanban orchestrator reads profile descriptions. You can read or set a profile's description using the describe command:

hermes profile describe coder --text "Handles code review and terminal execution"

To delete an isolated profile when it is no longer needed, run the delete command:

hermes profile delete mybot

Persist files for your Hermes Agent profiles

Deploy shared Fast.io workspaces with version history and natural language document extraction to support multiple concurrent agent roles. Starts with a 14-day free trial.

Start 14-Day Trial

Few guides explain how to share or distribute profiles via Git repositories using the hermes profile install command. Rather than manually copying config files, API keys, and custom scripts to new servers, you can package a complete agent configuration into a Git repository. This lets teams share pre-configured agent roles, including personality guidelines, scheduled tasks, and allowed tools.

To install a profile distribution from a public or private Git repository, use the profile install command and specify a custom name:

hermes profile install github.com/username/hermes-profile-coder --alias remote-coder

This command clones the repository, verifies the configuration files, and initializes the profile directory. To update a Git-managed profile to the latest release, run the update command:

hermes profile update remote-coder

This pulls the latest commits from the Git remote and re-applies the configuration without overwriting local sessions or API keys. To inspect where a profile was installed from, check its metadata using the info command:

hermes profile info remote-coder

This returns the source Git URL, the active commit hash, and the timestamp of the last update. Using Git-based distribution allows teams to version-control their agent configurations, track changes over time, and deploy standardized agents across staging and production servers.

Few guides explain how to set up home mode for separate SSH or Git credentials. By default, when Hermes Agent spawns terminal commands, standard subprocesses inherit the host machine's home directory. This means the agent reads SSH keys from ~/.ssh/ and uses the Git configurations from ~/.gitconfig. If you run a client-facing agent, it may accidentally use your personal SSH keys or commit code under your personal Git identity.

To isolate CLI credentials between different profiles, enable the home mode setting in the profile's config.yaml file. Open ~/.hermes/profiles//config.yaml and insert the home_mode variable under the terminal block:

terminal:
  backend: local
  home_mode: profile

When home_mode is set to profile, Hermes overrides the HOME environment variable for all spawned subprocesses. It maps the home directory to a nested folder inside the profile directory:

~/.hermes/profiles/<name>/home/

With this setting active, the agent reads and writes credentials only within this isolated path. To set up separate credentials, create the isolated directory structure:

mkdir -p ~/.hermes/profiles/client-acme/home/.ssh/

Place the client-specific SSH key inside this directory:

~/.hermes/profiles/client-acme/home/.ssh/id_ed25519

Configure the agent's Git identity by writing a local .gitconfig file:

~/.hermes/profiles/client-acme/home/.gitconfig

Write the user block inside this file:

[user]
  name = "ACME Coding Bot"
  email = "agent.acme@client-domain.com"

When the agent runs git push or SSH commands, it reads only the keys and identity defined inside its local profile directory. For details on running local tools with persistent storage, visit the Fast.io developer storage page. The real home directory path is still exposed to subprocesses via the HERMES_REAL_HOME environment variable, allowing custom tools to reference global configurations if needed.

Running multiple Hermes Agent profiles on a server creates a new challenge: how to persist and share files between isolated instances. Storing files locally on the host server limits access to a single machine, making it difficult to run agents across multiple cloud instances. Raw cloud storage buckets like Amazon S3 resolve the persistence issue but require developers to write custom API logic to search files, handle credentials, or keep track of versions. Shared folders on consumer cloud storage services like Google Drive suffer from rate limits and lack built-in tools for agent execution.

Fast.io provides a persistent cloud workspace designed for agentic teams. Instead of managing complex directory structures, you can hook your Hermes Agent profiles up to a shared workspace. Fast.io functions as the central storage layer where agents write code, store reports, and hand off assets to human teammates.

This integration provides key features for multi-agent coordination:

Per-File Version History: When multiple agent instances write to the same files, concurrent updates can cause data loss. Fast.io keeps a complete version history for every file, letting you inspect edits and roll back to previous versions.

Structured Extraction with Metadata Views: Using Metadata Views, agents turn documents into structured databases. By describing required fields in natural language, the system populates a spreadsheet with extracted data from PDFs, images, or notes. For developers setting up automated extraction, the Metadata Views product page provides implementation guides.

Consolidated MCP Toolset: Fast.io exposes Model Context Protocol access via Streamable HTTP at /mcp and legacy SSE at /sse. This allows your Hermes Agent profiles to connect to the workspace without local database dependencies.

Agent-to-Human Handoff: When an agent completes a task, it can transfer ownership of files or entire folders to a human manager. Humans use the Fast.io dashboard UI to review notes, while agents read and write via API keys configured in their profile's local .env file. Organizers can configure these workspaces under a Starter subscription for $29/mo, Business for $99/mo, or Growth for $299/mo. Every organization starts with a 14-day free trial, which requires a credit card to activate.