Build Your AI Workspace

Configure a specialized AI agent with custom skills and MCP tools.

Introduction

30 Second Summary

Most AI assistants come ready to do a little of everything. That sounds great until you need one that's actually good at a specific job.

In this project, you will build a specialized AI agent using Hermes Agent's Web Dashboard. You'll configure it with a hand-picked model, curated skills, and structured file access, then put it to work analyzing a real codebase and producing a README draft.

What You'll Build

You'll watch your custom agent read through real source code and produce a polished README draft you could paste straight into a repository.

By the end of this project, you'll have:

A custom agent profile built through a browser-based wizard with a hand-picked model, curated skills, and a filesystem MCP server for structured file access.
A real deliverable your agent produced: a detailed project analysis and README draft for the Hermes Agent source code.
The ability to switch between agent profiles from the dashboard sidebar and see how a purpose-built specialist outperforms a generic default.
Secret Mission: Give your agent a custom identity via SOUL.md, install a community skill from the Skills Hub, and run a real code review on production source code.

Are there any prerequisites?

This project uses Hermes Agent, Node.js, and an OpenRouter account. If you don't have any of these set up yet, Step 1 includes tabs with full instructions for each one.

Before We Start

Before We Start...

Before any hands-on work, let's lock in what you're about to build and why it matters. This step is your chance to commit to the goal before diving into tools and configuration.

Set Up Your Tools

Before you can configure agents in the browser, you need three pieces in place. Hermes Agent provides the agent runtime. Node.js powers the MCP servers you'll connect later. OpenRouter gives your agent access to free AI models.

In this step, you'll verify each tool is ready, install the extra packages the dashboard needs, and launch the Hermes Web Dashboard for the first time.

In this step, get ready to:

Verify Hermes Agent, Node.js, and OpenRouter are ready.
Install dashboard extras and connect OpenRouter as your model provider.
Launch the Hermes Web Dashboard and confirm it's running.

Check your prerequisites

You need three tools before moving forward. Let's verify each one and set up anything that's missing.

Confirm Hermes Agent is installed by running this command:

hermes --version

✔️ I see a version number

Hermes Agent is ready. Move on to the Node.js check below.

ⓧ Hermes is not installed

You need Hermes Agent installed before continuing this project.

Complete the Set Up Hermes Agent for Free project on NextWork first.
Come back here once you have Hermes running.

Confirm Node.js is installed by running:

node --version

✔️ I see a version number

Node.js is ready. Move on to the OpenRouter check below.

ⓧ Command not found

Node.js is required for MCP servers and the dashboard frontend.

Download and install Node.js from nodejs.org. Choose the LTS version.
After installing, close and reopen your terminal.
Verify the install by running:

node --version

You should now see a version number printed in your terminal.

Confirm you have an OpenRouter account and an API key ready. You'll need the key in the next substep.

✔️ I have my API key ready

You're all set. Keep your API key handy for the next substep.

ⓧ I need an OpenRouter account

OpenRouter's free tier includes 25+ free models. No credit card required.

Go to openrouter.ai.
Click Sign Up For Free and create your account.
After signing in, navigate to your API keys settings page.
Click Create Key to generate a new API key.
Copy the key. It starts with sk-or-. You'll use it in the next substep.

Save your API key somewhere safe

OpenRouter only shows the full key once at creation time. Paste it into a text file or password manager before closing the dialog.

Install dashboard extras and connect OpenRouter

The Hermes dashboard needs extra Python packages that aren't included in the default install. These packages power the web server and the browser-based terminal.

Install the dashboard dependencies by running this command:

cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"

What does this command do?

cd ~/.hermes/hermes-agent moves into the Hermes Agent source directory on your machine.
uv pip install -e ".[web,pty]" installs two optional dependency groups: web (which adds FastAPI and Uvicorn for the web server) and pty (which adds terminal emulation for the in-browser chat).

You should see output showing packages being resolved and installed, ending with lines like Installed X packages and no error messages.

Seeing a path error?

Make sure Hermes Agent is fully installed. The directory ~/.hermes/hermes-agent should exist on your machine. If it doesn't, go back and complete the Hermes Agent setup project first.
If you see a uv: command not found error, Hermes installs uv during its own setup. Restart your terminal and try again.

Help me fix my dashboard extras installation.

Now connect OpenRouter as your model provider. The hermes model command launches an interactive picker that walks you through choosing a provider, entering your API key, and selecting a model.

Start the interactive model selector by running:

hermes model

Select OpenRouter from the provider list.
Enter your API key when prompted. Hermes automatically saves it to ~/.hermes/.env.
Pick any free model from the list. Look for models with "free" in the name.

Which model should I pick?

Hermes requires a model with at least 64,000 tokens of context. Any model labeled "free" that meets this threshold works. If a model is rejected at startup, Hermes tells you why.

You can always change your model later by running hermes model again.

The interactive session confirms your selection when complete. Your model and API key are now saved.

API key not accepted?

Double-check that you copied the full key. It should start with sk-or-.
If you accidentally created a key with restrictions, generate a new unrestricted key from your OpenRouter API keys settings page.

Help me troubleshoot my OpenRouter connection in Hermes.

Launch the dashboard

Everything is installed and configured. Before you run the next command, take a guess: what kind of information do you think the dashboard's Status page will show about your agent?

Launch the Hermes Web Dashboard by running:

hermes dashboard

Your browser opens to http://127.0.0.1:9119. The Status page shows your agent version, gateway status, and active sessions. The dashboard runs entirely on your machine.

What is the Hermes Web Dashboard?

The dashboard is a browser-based control center for your Hermes Agent. It lets you manage profiles, configure models and skills, attach MCP servers, and chat with your agent. Everything stays local on your machine.

The terminal running hermes dashboard needs to stay open. If you close it, the dashboard stops.

Browser didn't open?

Open your browser manually and go to http://127.0.0.1:9119.
If you see a connection error, check that the hermes dashboard command is still running in your terminal. It should show log output confirming the server started.
If the command failed with a missing package error, re-run the install extras command from the previous substep.

Help me get the Hermes dashboard running.

Your environment is ready. Next up, you'll chat with the default agent through the dashboard and see what a generic, uncustomized setup looks like before building something better.

Chat with the Default Agent

Your tools are installed, OpenRouter is connected, and the dashboard is running. Now it's time to put your setup to the test by talking to your agent.

In this step, you'll chat with the default agent through the dashboard and see exactly what a generic, uncustomized agent looks like. Understanding the default profile's configuration is how you'll know what to improve when you build a specialized agent in the next step.

In this step, get ready to:

Send your first message and inspect the default agent's configuration.
Ask the default agent to analyze a real codebase directory and observe how it responds.

Send your first message

The Chat tab in the dashboard runs the full Hermes TUI inside your browser. It connects to your agent just like a terminal session, but through a web interface.

In the dashboard at http://127.0.0.1:9119, click Chat in the sidebar.

The Chat tab opens with an embedded terminal session. You'll see a text prompt where you can type messages to your agent.

Before you type anything, think about this. You haven't configured any MCP servers yet. What do you think the agent will report when you ask about its connections?

Type this message into the chat and press Enter:

Hello! Tell me what model you're running, how many skills you have loaded, and whether you have any MCP servers connected.

The agent responds with its current configuration. It reports the free model you selected, dozens of bundled skills, and zero MCP servers.

What did the agent reveal?

The agent is running your selected OpenRouter free model.
It has all bundled skills loaded. That's dozens of skills, covering everything from coding to social media.
It reports zero MCP servers connected. The agent has no structured integrations with external tools or file systems.
This is the default profile: a generalist with every skill active, a generic identity, and nothing customized.

Not seeing a response?

Make sure the dashboard is still running in your terminal. If you closed the terminal or pressed Ctrl+C, run hermes dashboard again.
Check that your OpenRouter API key is valid. The agent needs a working API connection to generate a response.
If the chat shows a connection error, refresh the browser page at http://127.0.0.1:9119 and try sending your message again.
Why isn't the Hermes agent responding in the Chat tab?

Ask the default agent to analyze a directory

Your agent responded, which proves the setup works end-to-end. Now let's ask it to do something more demanding. You'll point it at the Hermes Agent source code and ask for a structured analysis.

The default agent has all its built-in tools but no filesystem MCP server. Do you think it can still produce a useful project analysis using only basic terminal commands?

Type this message into the chat and press Enter:

Analyze the directory at ~/.hermes/hermes-agent/ and give me a structured project summary. Include: what this project is, its main programming language, the top-level directory layout, and what the 3 most important files are.

The agent uses its built-in terminal and file-reading tools to explore the directory. It returns a structured project summary with the information you requested.

What's happening under the hood?

The agent relied on basic shell commands to read files and list directories. It has no MCP filesystem server, so it has no structured way to browse your project files.

On top of that, all 40+ tools are loaded and every bundled skill is active. That means the agent is spending context tokens on capabilities it doesn't need for this task. It works, but it's a blunt instrument.

The default agent got the job done, but it's running with every tool, every skill, and no structured file access. Next up, you'll use the Profile Builder to create a focused agent that cuts the noise and adds a real filesystem MCP server.

Build a Custom Agent with the Profile Builder

In the last step, you chatted with the default agent and saw it analyze a directory. It responded, but everything about that interaction was generic.

The agent loaded every bundled skill, had no structured file access, and wasted context tokens on irrelevant capabilities. The Profile Builder lets you create a focused agent profile with only what you need, entirely from the dashboard.

In this step, get ready to:

Open the Profile Builder wizard and set your agent's identity.
Select a model and curate skills for development work.
Attach a filesystem MCP server and create the profile.

Open the Profile Builder

Click Profiles in the sidebar.

You see your default profile card. This is the only profile you have so far.

Click the Build button in the page header.

The Profile Builder opens at /profiles/new. It walks you through five steps: Identity, Model, Skills, MCPs, and Review.

In the Name field, enter dev-assistant.
In the Description field, enter Focused development assistant for codebase analysis and code review.
Click Next.

Why does the name matter?

Profile names only accept lowercase letters, digits, hyphens, and underscores. A descriptive name like dev-assistant makes it easy to identify this profile in the sidebar and when using it from the CLI with hermes -p dev-assistant.

The wizard advances to the Model step.

Select your model and curate skills

The Model step shows a dropdown of providers and models in a flat list. You already connected OpenRouter in Step 1, so your free models appear here.

Select an OpenRouter free model from the dropdown (look for models with "free" in the name, such as a Llama or Nemotron free model).
Click Next.

Which free model should I pick?

OpenRouter offers 25+ free models from 4 free providers. Any free model will work for this project as long as it has at least 64,000 tokens of context.

Hermes rejects models with smaller context windows at startup, so if a model appears in the dropdown, it meets the requirement.

The wizard advances to the Skills step. You see a list of bundled skills with toggles next to each one.

This is where specialization starts. Instead of keeping every skill active, you disable the ones unrelated to your development work.

Disable skills that are unrelated to development work (for example, messaging-focused, social media, or entertainment skills).
Keep skills related to coding, file operations, and development workflows toggled on.
Click Next.

Not sure which skills to disable?

If you are unsure, keep the "Start from full bundle" toggle on and move forward. You can always refine your skills later by editing the profile.

Add a filesystem MCP server, review, and create

The MCPs step lets you attach MCP servers that give your agent structured access to external tools and data. You are going to add a filesystem MCP server so your agent can read files on your machine through a proper protocol instead of basic terminal commands.

Find your home directory path

You need your absolute home directory path for the next field. If you do not know it, open a new terminal window (your dashboard is still running in the other one) and run:

echo $HOME

Copy the output (for example, /home/youruser). You will paste it in the args field below.

Add a stdio MCP server with the following fields.
In the Command field, enter npx.
In the Args field, enter -y, @modelcontextprotocol/server-filesystem, and your absolute home directory path (the value you copied from echo $HOME).

What is a filesystem MCP server?

MCP (Model Context Protocol) servers give your agent structured access to external tools and data sources. The filesystem MCP server lets your agent read files and navigate directories through a dedicated protocol instead of running raw terminal commands.

It only requires Node.js (which you installed in Step 1) and no additional API keys or accounts. The directory path you provide is the sandbox boundary. Your agent can only access files inside it.

Click Next to reach the Review step.

The Review step shows a summary of everything you configured: your profile name, model, skill configuration, and MCP server. Take a moment to verify each section looks correct.

Click Create profile.

A success toast confirms your profile was created.

Before you navigate back to the Profiles page, what do you expect to see there now compared to when you first opened it?

Click Profiles in the sidebar.

Your dev-assistant card now appears alongside the default profile. It shows your selected model, a reduced skill count, and a badge indicating the attached MCP server.

Don't see your dev-assistant profile card?

Make sure you clicked Create profile on the Review step and saw the success toast. If you navigated away before clicking it, return to /profiles/new and walk through the wizard again.
If the profile name field showed an error, check that you used only lowercase letters, digits, hyphens, or underscores. Names like Dev-Assistant (uppercase) are not accepted.
Why isn't my dev-assistant profile showing up on the Profiles page?

Your specialized agent is built. Next up, you will switch to your dev-assistant profile and put it to real work analyzing the Hermes Agent codebase.

Put Your Custom Agent to Real Work

Your custom dev-assistant profile is built and visible on the Profiles page. Now it's time to put it to work.

A configured agent is only valuable if it produces better results than the default. You'll switch to your custom profile, repeat the same codebase analysis from Step 2, and see firsthand how a focused agent with structured file access compares to a generic one.

In this step, get ready to:

Switch to your dev-assistant profile and confirm the dashboard scopes to it.
Run the same codebase analysis prompt and compare the output against the default agent's earlier response.
Generate a complete README draft for the Hermes Agent project.

Switch to your custom profile

The profile switcher in the sidebar scopes the entire dashboard to a specific profile. Every page and session reflects whichever profile you select.

In the sidebar, click the profile switcher dropdown.
Select dev-assistant from the list.

An amber banner appears at the top of the page. This confirms you're now managing the dev-assistant profile.

Click Chat in the sidebar.

A fresh terminal session spawns running with your custom profile's model, curated skills, and MCP filesystem tools.

Don't see the profile switcher?

The profile switcher only appears when more than one profile exists. Return to the Profiles page and confirm your dev-assistant card is listed alongside the default profile.

Still stuck? Help me troubleshoot why the profile switcher isn't showing in my Hermes dashboard.

Run the same analysis with your specialized agent

In Step 2, you asked the default agent to analyze the Hermes Agent codebase. It relied on generic terminal commands with every bundled skill loaded.

Now you'll send the exact same prompt to your custom agent and compare the results.

Before you send this prompt, think about what you expect to be different. Your custom agent has MCP filesystem tools for structured file access and fewer irrelevant skills consuming context.

Type this prompt into the Chat tab and press Enter:

Analyze the directory at ~/.hermes/hermes-agent/ and give me a structured project summary. Include: what this project is, its main programming language, the top-level directory layout, and what the 3 most important files are.

What should I compare?

Your custom agent now has MCP filesystem tools for structured file access alongside its built-in tools. It also has fewer irrelevant skills consuming context.

The output should be more focused and detailed because the agent isn't spreading its attention across dozens of unrelated capabilities.

The agent responds with a structured project summary. Compare it against the response you got in Step 2 from the default agent.

Agent not responding?

Check that the amber banner still shows dev-assistant as the active profile. If it switched back to default, reselect it from the sidebar.
If you see a rate limit error, wait a minute and try again. The free tier allows 20 requests per minute.
If the terminal session looks frozen, press Ctrl+C and retype your prompt.

Need more help? Help me debug why my Hermes agent isn't responding in the Chat tab.

Generate a real deliverable

Your custom agent proved it can analyze code with more focus than the default. Now push it further by asking it to produce something you could actually use.

Before you send this next prompt, what do you expect the README to include? Do you think the agent can produce a complete, formatted Markdown document you could paste directly into a file?

Type this prompt into the Chat tab and press Enter:

Based on your analysis, write a README.md for this project. Include a project description, key features, installation instructions, directory structure overview, and a "Getting Started" section. Format it as valid Markdown I could paste into a file.

The agent produces a complete, formatted README draft. This is real output from your custom workspace: a deliverable you created by configuring a specialized agent and pointing it at a real codebase.

README output looks incomplete?

If the output was cut short, the model may have hit its output token limit. Try sending a follow-up prompt asking the agent to continue where it left off.
If the README is missing sections, resend the prompt and explicitly list each section you want (project description, key features, installation, directory structure, Getting Started).

Still not getting good results? Help me improve my agent's README output.

Your custom agent just analyzed a real codebase and produced a usable README draft. Next up, the Secret Mission takes your agent even further with a custom identity and community skills.

Secret mission

Give Your Agent a Custom Identity and New Skills

Your dev-assistant has the right model, curated skills, and a filesystem MCP server. But it still responds like a generic AI. Give it a custom identity through SOUL.md, install a skill from the community Skills Hub, and prove the difference with a real code review on production source code.

Clean Up Your Resources

This project runs entirely on your machine and uses OpenRouter's free tier, so there are no ongoing costs. Decide whether to keep your resources, pause them to come back later, or delete them entirely.

Resources you used:

dev-assistant profile at ~/.hermes/profiles/dev-assistant/ (includes your model selection, curated skills, MCP server config, and SOUL.md identity).
OpenRouter API key stored in ~/.hermes/.env.
Hermes Web Dashboard process running in your terminal.

Keep everything running

No action needed. Choose this if you plan to keep using your dev-assistant agent.

Your dev-assistant profile persists at ~/.hermes/profiles/dev-assistant/.
The dashboard is available whenever you run hermes dashboard.
You can also use the profile from the CLI with hermes -p dev-assistant.
Your OpenRouter API key stays configured in ~/.hermes/.env for all profiles.
Any Skills Hub skills you installed remain in ~/.hermes/skills/ and are available to all profiles.

Pause - I'll come back to this later

Shut down the dashboard process to free up your terminal. Your profiles, skills, and configuration remain on disk.

Press Ctrl+C in the terminal where the dashboard is running to stop it.
Restart anytime by running hermes dashboard.

Delete - I don't want to use this again

Remove the custom profile you created during this project. This does not affect your default Hermes profile.

Stop the dashboard by pressing Ctrl+C in the terminal where it is running.
Remove your dev-assistant profile by running:

hermes profile delete dev-assistant

This removes the profile directory at ~/.hermes/profiles/dev-assistant/ and its configuration, including your custom SOUL.md and skill selections.

Your OpenRouter API key remains in ~/.hermes/.env. To remove it, open the file in a text editor and delete the line containing OPENROUTER_API_KEY.

Nice Work!

You just built a specialized AI agent from scratch, configured it entirely through a browser, and used it to produce real, usable output on a real codebase.

You've learned how to:

Connected Hermes Agent to OpenRouter's free tier and launched the Web Dashboard to chat with an AI agent, inspect its configuration, and see exactly what model, tools, and skills it was running.
Built a custom dev-assistant profile using the Profile Builder wizard with a hand-picked model, curated skills, and a filesystem MCP server for structured file access.
Put your custom agent to real work by analyzing the Hermes Agent codebase and generating a complete, formatted README draft you could paste straight into a repository.
Secret Mission: Gave your agent a custom identity via SOUL.md, installed a skill from the Skills Hub, and ran a real code review on production source code.

Ready to quiz yourself?