Tools, Toolsets, and Sandboxed Code Execution

From "It Just Works" to Actually Understanding It

Hermes Agent Fundamentals showed you that tools work by default with zero configuration. This lesson is the deeper version of that: the full catalog of what exists, organized into toolsets, and how to control which ones are active for a given session or platform.

The Toolset Catalog

• Web -- web_search, web_extract
• X/Twitter Search -- x_search, post and thread searching via xAI
• Terminal & Files -- terminal, process, read_file, patch
• Browser -- interactive web automation (full lesson later in this track)
• Media -- multimodal analysis and generation (also a later lesson)
• Agent Orchestration -- todo, clarify, execute_code, delegate_task
• Memory -- persistent storage and retrieval, from Fundamentals Lesson 8
• Automation & Delivery -- cronjob, send_message
• Integrations -- Home Assistant, MCP servers (next lesson)

Controlling Which Toolsets Are Active

hermes chat --toolsets "web,terminal"   # Only these toolsets, for this run
hermes tools                            # View and interactively configure

This matters most once you start running agents in contexts where you want to restrict capability deliberately -- a customer-facing bot probably should not have unrestricted terminal access, for instance, even if your personal CLI session should.

Sandboxed Code Execution: The Advanced Tool

execute_code is a different kind of tool from everything above. Instead of calling one tool, getting a result, and deciding what to do next in a loop, the agent writes an actual Python script that calls Hermes tools programmatically:

from hermes_tools import web_search, web_extract

results = web_search("Rust async runtime comparison 2025", limit=5)
summaries = []
for r in results["data"]["web"]:
    page = web_extract([r["url"]])
    for p in page.get("results", []):
        if p.get("content"):
            summaries.append({
                "title": r["title"],
                "url": r["url"],
                "excerpt": p["content"][:500]
            })
print(json.dumps(summaries, indent=2))

Only the script's print() output comes back to the model -- not every intermediate tool result. For a research task hitting five URLs, that is the difference between five full page extractions flooding the context window and one clean, pre-filtered JSON summary.

How It Actually Runs

Hermes generates a stub module called hermes_tools.py with RPC functions, opens a Unix domain socket, and starts an RPC listener thread. The script runs in a child process, and every tool call inside it travels over that socket back to the parent process rather than executing locally. This is why the feature is Linux and macOS only -- Windows lacks the Unix domain socket primitive this depends on, and automatically falls back to sequential tool calls instead.

Tools available inside a script: web_search, web_extract, read_file, write_file, search_files, patch, and terminal (foreground only inside a script).

When the Agent Reaches for This Automatically

You do not have to explicitly request code execution -- the agent deploys it on its own for:

• Three or more sequential tool calls with real processing logic in between
• Bulk data filtering or conditional branching across results
• Loops over a result set

A single tool call, or two unrelated ones, will not trigger this -- it is specifically for the case where stringing together raw tool calls one at a time would be both slow and would flood the context with intermediate noise.

Two Execution Modes

Strict mode is the more isolated of the two -- reach for it when you want the script unable to read or write your real project files at all.

Resource Limits

• 5 minute maximum timeout
• 50 KB stdout cap, 10 KB stderr cap
• 50 tool calls per execution, maximum

Security: Credentials Are Stripped by Default

The child process runs with deliberately minimal environment exposure. Any environment variable whose name contains KEY, TOKEN, SECRET, PASSWORD, CREDENTIAL, PASSWD, or AUTH is automatically excluded -- API keys, tokens, and credentials simply are not visible inside the script's environment by default. Skills can declare required environment variables in their own frontmatter to pass specific ones through deliberately, and you can allowlist additional variables in config.yaml if a particular workflow genuinely needs one.

The next lesson covers a complementary safety feature: checkpoints and rollback, which protect your actual files when the agent is making destructive-looking changes, separate from the code-execution sandbox covered here.