164 lines
5.7 KiB
Markdown
164 lines
5.7 KiB
Markdown
---
|
|
sidebar_position: 1
|
|
title: "Tools & Toolsets"
|
|
description: "Overview of Hermes Agent's tools — what's available, how toolsets work, and terminal backends"
|
|
---
|
|
|
|
# Tools & Toolsets
|
|
|
|
Tools are functions that extend the agent's capabilities. They're organized into logical **toolsets** that can be enabled or disabled per platform.
|
|
|
|
## Available Tools
|
|
|
|
Hermes ships with a broad built-in tool registry covering web search, browser automation, terminal execution, file editing, memory, delegation, RL training, messaging delivery, Home Assistant, Honcho memory, and more.
|
|
|
|
High-level categories:
|
|
|
|
| Category | Examples | Description |
|
|
|----------|----------|-------------|
|
|
| **Web** | `web_search`, `web_extract` | Search the web and extract page content. |
|
|
| **Terminal & Files** | `terminal`, `process`, `read_file`, `patch` | Execute commands and manipulate files. |
|
|
| **Browser** | `browser_navigate`, `browser_snapshot`, `browser_vision` | Interactive browser automation with text and vision support. |
|
|
| **Media** | `vision_analyze`, `image_generate`, `text_to_speech` | Multimodal analysis and generation. |
|
|
| **Agent orchestration** | `todo`, `clarify`, `execute_code`, `delegate_task` | Planning, clarification, code execution, and subagent delegation. |
|
|
| **Memory & recall** | `memory`, `session_search`, `honcho_*` | Persistent memory, session search, and Honcho cross-session context. |
|
|
| **Automation & delivery** | `cronjob`, `send_message` | Scheduled tasks with create/list/update/pause/resume/run/remove actions, plus outbound messaging delivery. |
|
|
| **Integrations** | `ha_*`, MCP server tools, `rl_*` | Home Assistant, MCP, RL training, and other integrations. |
|
|
|
|
For the authoritative code-derived registry, see [Built-in Tools Reference](/docs/reference/tools-reference) and [Toolsets Reference](/docs/reference/toolsets-reference).
|
|
|
|
## Using Toolsets
|
|
|
|
```bash
|
|
# Use specific toolsets
|
|
hermes chat --toolsets "web,terminal"
|
|
|
|
# See all available tools
|
|
hermes tools
|
|
|
|
# Configure tools per platform (interactive)
|
|
hermes tools
|
|
```
|
|
|
|
Common toolsets include `web`, `terminal`, `file`, `browser`, `vision`, `image_gen`, `moa`, `skills`, `tts`, `todo`, `memory`, `session_search`, `cronjob`, `code_execution`, `delegation`, `clarify`, `honcho`, `homeassistant`, and `rl`.
|
|
|
|
See [Toolsets Reference](/docs/reference/toolsets-reference) for the full set, including platform presets such as `hermes-cli`, `hermes-telegram`, and dynamic MCP toolsets like `mcp-<server>`.
|
|
|
|
## Terminal Backends
|
|
|
|
The terminal tool can execute commands in different environments:
|
|
|
|
| Backend | Description | Use Case |
|
|
|---------|-------------|----------|
|
|
| `local` | Run on your machine (default) | Development, trusted tasks |
|
|
| `docker` | Isolated containers | Security, reproducibility |
|
|
| `ssh` | Remote server | Sandboxing, keep agent away from its own code |
|
|
| `singularity` | HPC containers | Cluster computing, rootless |
|
|
| `modal` | Cloud execution | Serverless, scale |
|
|
| `daytona` | Cloud sandbox workspace | Persistent remote dev environments |
|
|
|
|
### Configuration
|
|
|
|
```yaml
|
|
# In ~/.hermes/config.yaml
|
|
terminal:
|
|
backend: local # or: docker, ssh, singularity, modal, daytona
|
|
cwd: "." # Working directory
|
|
timeout: 180 # Command timeout in seconds
|
|
```
|
|
|
|
### Docker Backend
|
|
|
|
```yaml
|
|
terminal:
|
|
backend: docker
|
|
docker_image: python:3.11-slim
|
|
```
|
|
|
|
### SSH Backend
|
|
|
|
Recommended for security — agent can't modify its own code:
|
|
|
|
```yaml
|
|
terminal:
|
|
backend: ssh
|
|
```
|
|
```bash
|
|
# Set credentials in ~/.hermes/.env
|
|
TERMINAL_SSH_HOST=my-server.example.com
|
|
TERMINAL_SSH_USER=myuser
|
|
TERMINAL_SSH_KEY=~/.ssh/id_rsa
|
|
```
|
|
|
|
### Singularity/Apptainer
|
|
|
|
```bash
|
|
# Pre-build SIF for parallel workers
|
|
apptainer build ~/python.sif docker://python:3.11-slim
|
|
|
|
# Configure
|
|
hermes config set terminal.backend singularity
|
|
hermes config set terminal.singularity_image ~/python.sif
|
|
```
|
|
|
|
### Modal (Serverless Cloud)
|
|
|
|
```bash
|
|
uv pip install "swe-rex[modal]"
|
|
modal setup
|
|
hermes config set terminal.backend modal
|
|
```
|
|
|
|
### Container Resources
|
|
|
|
Configure CPU, memory, disk, and persistence for all container backends:
|
|
|
|
```yaml
|
|
terminal:
|
|
backend: docker # or singularity, modal, daytona
|
|
container_cpu: 1 # CPU cores (default: 1)
|
|
container_memory: 5120 # Memory in MB (default: 5GB)
|
|
container_disk: 51200 # Disk in MB (default: 50GB)
|
|
container_persistent: true # Persist filesystem across sessions (default: true)
|
|
```
|
|
|
|
When `container_persistent: true`, installed packages, files, and config survive across sessions.
|
|
|
|
### Container Security
|
|
|
|
All container backends run with security hardening:
|
|
|
|
- Read-only root filesystem (Docker)
|
|
- All Linux capabilities dropped
|
|
- No privilege escalation
|
|
- PID limits (256 processes)
|
|
- Full namespace isolation
|
|
- Persistent workspace via volumes, not writable root layer
|
|
|
|
## Background Process Management
|
|
|
|
Start background processes and manage them:
|
|
|
|
```python
|
|
terminal(command="pytest -v tests/", background=true)
|
|
# Returns: {"session_id": "proc_abc123", "pid": 12345}
|
|
|
|
# Then manage with the process tool:
|
|
process(action="list") # Show all running processes
|
|
process(action="poll", session_id="proc_abc123") # Check status
|
|
process(action="wait", session_id="proc_abc123") # Block until done
|
|
process(action="log", session_id="proc_abc123") # Full output
|
|
process(action="kill", session_id="proc_abc123") # Terminate
|
|
process(action="write", session_id="proc_abc123", data="y") # Send input
|
|
```
|
|
|
|
PTY mode (`pty=true`) enables interactive CLI tools like Codex and Claude Code.
|
|
|
|
## Sudo Support
|
|
|
|
If a command needs sudo, you'll be prompted for your password (cached for the session). Or set `SUDO_PASSWORD` in `~/.hermes/.env`.
|
|
|
|
:::warning
|
|
On messaging platforms, if sudo fails, the output includes a tip to add `SUDO_PASSWORD` to `~/.hermes/.env`.
|
|
:::
|