Profiles: Isolated Agent Contexts

By this point in the course, your Hermes setup has accumulated: a default model you chose on Day 1, skills for your main project, cron jobs for that project's maintenance tasks, memory entries from dozens of sessions, and maybe a Gateway configuration from Day 3. Then you start a second project. It needs a different model. It needs its own skills. Its cron jobs should never see the first project's database credentials. And its memory file should not be cluttered with conversations about a codebase it has never touched.

Profiles give you clean walls between projects. Each profile is a self-contained Hermes configuration, its own model, skills, cron table, memory database, plugins, and Gateway config. Switch between them with one command.

What you'll learn

• A profile is a complete Hermes configuration silo: model, skills, cron jobs, memory, plugins, and Gateway settings all live in ~/.hermes/profiles/<name>/
• hermes profile create spawns a new profile, hermes profile use switches the active context, and the --profile flag overrides per-command
• Cloning copies an existing profile wholesale, skills, cron jobs, and config, so you can fork a project's Hermes setup without rebuilding from scratch
• Export and import move profiles between machines, making it possible to version-control your agent configuration alongside your project

The problem

You work on three projects: a Python API, a React dashboard, and a set of infrastructure scripts. The API project uses anthropic/claude-sonnet-4 for code generation, the dashboard works better with openai/gpt-4o for UI reasoning, and the infra scripts need deepseek/deepseek-v4-pro because it is cheaper for repetitive shell commands. Without profiles, you change the model by hand every time you switch projects. Or worse, you do not change it, and you wonder why the React agent keeps writing Python.

Skills compound the problem. The API project has a postgresql-inspection skill and a flask-blueprint-extraction skill. The dashboard has a react-component-decomposition skill and a popular-web-designs skill. If all skills are loaded into one Hermes context, every agent run sees all skills from all projects. The API agent wastes tokens reading about React patterns it will never use. The dashboard agent gets confused by Flask conventions. And a cron job for the infra project could accidentally use a skill that references API database credentials.

Options & when to use each

Approach	Good for	Costs you	When to pick it
Profiles	Complete isolation between projects, models, skills, cron, memory, plugins	Disk space for each profile directory (~10-50MB), mental overhead of remembering which profile is active	Multiple projects with genuinely different needs. The default for anyone running Hermes in more than one context
Single profile, manual switching	One project, or projects that genuinely share the same model, skills, and cron table	Context pollution, skill and memory leakage between projects	A single-project setup where isolation is not worth the overhead
--model and --skills flags per command	Quick overrides without creating a profile	Not persistent, no cron isolation, no memory isolation	Occasional one-off tasks in a different domain, like "use the image generation model just for this one render"
Profiles with shared base via cloning	Projects that start from the same foundation but diverge	You have to maintain the shared base manually, cloning is a point-in-time copy, not a live link	When a new project is a fork of an existing one and should start with the same Hermes setup

Build it

Step 1: List existing profiles and check which one is active

List all available profiles to see your current workspace context. The active profile is marked in the output.

hermes profile list

Output shows all profiles, with the active one marked. On a fresh install, you have one profile: default. Everything you have built so far, the model from Day 1, the skills from Day 2, the Gateway from Day 3 , lives in ~/.hermes/profiles/default/.

Step 2: Create a new profile

Generate a fresh profile for your new project. This creates an isolated configuration directory with a blank slate.

hermes profile create api-project

This creates ~/.hermes/profiles/api-project/ with a fresh configuration. The new profile starts blank, no custom model, no skills, no cron jobs, no memory. It inherits nothing from default.

To create a profile and switch to it immediately:

hermes profile create api-project --use

Step 3: Configure the new profile

After switching, configure it as if it were a fresh Hermes install:

# Switch to the new profile
hermes profile use api-project

# Set the model for this project
hermes config set model.default "anthropic/claude-sonnet-4"

# Install project-specific skills
hermes skills install postgresql-inspection
hermes skills install flask-blueprint-extraction

# Create cron jobs scoped to this project
hermes cron create db-health \
  --schedule "every 30m" \
  --prompt "Check the PostgreSQL connection pool health. Report connection count, idle timeouts, and any errors."

Everything you configure now stays inside the api-project profile. The default profile is untouched.

Step 4: Switch between profiles

Change your active context to another profile using the use command. Subsequent Hermes commands will run in the newly selected context.

# Switch contexts
hermes profile use api-project

# Run a one-shot in the API project's context
hermes chat -q "Check the API's error rate over the last hour"

# Switch to another project
hermes profile use dashboard-project
hermes chat -q "Review the new dashboard component for accessibility issues"

The prompt does not need to specify the project, the profile carries all the context. The model, the skills, and the working assumptions are already set.

Step 5: Use the --profile flag for one-off context switches

If you are mostly working in one profile but need a single command in another:

# Run a one-shot in the api-project profile without switching
hermes --profile api-project chat -q "Check the API logs for error spikes since 9 AM"

The --profile flag overrides the active profile for that one command. The active profile stays unchanged.

Step 6: Show profile details

Inspect the configuration and metadata of a specific profile. This shows the model, installed skills, and active cron jobs.

hermes profile show api-project

Output includes: the profile name, the directory path, the model configured, the number of skills installed, the number of cron jobs, and the last time the profile was used.

Step 7: Clone a profile

When a new project starts from the same foundation, clone instead of creating from scratch:

hermes profile clone api-project billing-api

The billing-api profile is a point-in-time copy of api-project. It has the same model, the same skills, and optionally the same cron jobs and memory. After cloning, switch to it and adjust: change the model if needed, add billing-specific skills, remove skills it does not need.

Step 8: Export and import profiles

Move a profile to another machine:

# On the source machine
hermes profile export api-project --output api-project.tar.gz

# Transfer the tarball (scp, rsync, USB drive)

# On the destination machine
hermes profile import api-project.tar.gz

The export includes the profile's config, skills, cron definitions, and plugin registry. It does not include the memory database (session history) by default, those are machine-specific. Use --include-memory to export session history too.

Step 9: Rename or delete a profile

Rename a profile to better reflect its purpose, or delete it permanently if it is no longer needed.

# Rename
hermes profile rename api-project api-v2

# Delete (irreversible, removes the directory and all its contents)
hermes profile delete old-experiment

Deleting the default profile is allowed but will break Hermes until you create a new one. Hermes always needs at least one profile.

Profile directory layout

Understanding what lives where helps when you need to troubleshoot or manually inspect:

~/.hermes/profiles/api-project/
├── config.yaml          # Model, provider, approval settings
├── .env                 # API keys (provider-specific)
├── skills/              # Installed skills (SKILL.md files)
├── cron/                # Cron job definitions
├── plugins/             # Desktop plugins and tool extensions
├── memories/            # USER.md, MEMORY.md, and the session database
└── gateway/             # Gateway configuration (from Day 3)

What goes wrong

Mistake	How you notice it	The fix
You run commands in the wrong profile	The agent uses the wrong model, references skills that do not exist for this project, or missing cron jobs do not fire	hermes profile list shows which profile is active. Run hermes profile show to see the full config. If you are switching profiles frequently, set your shell prompt to display the active profile: export PS1="[hermes:\$(hermes profile current 2>/dev/null)] $PS1"
Cloning a profile copies cron jobs that should not run in the new project	The cloned profile's cron jobs fire and reference databases or paths that do not exist in the new project	After cloning, immediately audit the cron table: hermes cron list. Remove or pause jobs that are project-specific. Clone is a convenience, not a live fork, treat it as a starting point, not a finished config
Exporting a profile with --include-memory and importing it on a different machine	Session history from the old machine references file paths that do not exist, and session_search returns confusing results	Only export memory when migrating to a machine with the same filesystem layout. For most cases, skip memory export, let the profile accumulate new session history on the new machine
Deleting the active profile while it is still in use	hermes commands fail with "profile not found"	Switch to another profile first: hermes profile use default. Then delete: hermes profile delete old-profile. Hermes prevents deletion of the currently active profile, so this error usually means you have a stale --profile reference in a cron job or script
Profile-specific API keys stored in the wrong place	Setting HERMES_API_KEY in the shell environment overrides all profile-specific keys, so switching profiles does not actually change the provider	Use profile-specific .env files (~/.hermes/profiles/<name>/.env) instead of shell environment variables. Shell env vars take precedence and are global, they defeat profile isolation

Confirm it worked

Verify profile isolation by creating a test profile, modifying its configuration, and checking that the changes do not affect the default profile.

# 1. Create a test profile
hermes profile create test-isolation

# 2. Switch to it and set a different model than your default
hermes profile use test-isolation
hermes config set model.default "deepseek/deepseek-v4-pro"

# 3. Verify the model is set
hermes config | grep "model:"

# 4. Switch back to default and confirm the model reverted
hermes profile use default
hermes config | grep "model:"

# 5. Run a one-shot in the test profile without switching
hermes --profile test-isolation chat -q "What model are you using? Just state the model name."

# 6. Clean up
hermes profile delete test-isolation

If step 3 shows deepseek/deepseek-v4-pro, step 4 shows your original model, and step 5 confirms the agent used the test profile's model, profile isolation is working.

Next: Day 5 , Production, Security & Extension , Docker deployment, command approval, secret redaction, MCP servers, and desktop plugins.