# Hermes

Hermes is an agent that can work with files, run commands, and use tools during a conversation. Actual can run Hermes on your computer for Console and [Hermes Desktop](/docs/hermes-desktop), or supply inference to a Hermes installation you manage yourself.

## Choose how to use Hermes

| How you connect | Where Hermes and its tools run | What you set up |
| --- | --- | --- |
| Agent in [Console Chat](/console/chat) | The selected Actual computer's managed workspace. | An online Actual computer and a loaded model. |
| [Hermes Desktop](/docs/hermes-desktop) with an Actual remote gateway | The connected Actual computer's managed workspace. | Desktop and a saved gateway connection. |
| Your own Hermes terminal installation | The computer or tool environment where you run Hermes. | Hermes, the Actual provider, and an inference credential. |

Selecting a remote model does not move a standalone Hermes installation's file and terminal tools to that model's computer. Use the managed Desktop gateway when you want to work in the Actual computer's workspace.

## Prepare your Actual computer

Follow [Getting Started](/docs/getting-started) to install Actual, authorize your computer, and [download and load a model](/docs/model-discovery). Choose a model with tool support and at least a 64K context window for Hermes. A successful connection alone does not mean the model is ready to run a task.

Keep the computer online while using Console Agent or the remote Desktop gateway. Actual's managed Hermes service is supported on macOS and Linux. Installing Actual on another platform does not imply managed Hermes is available there.

## Use Hermes in Console

Open [Console Chat](/console/chat), select your cluster and model, and choose **Agent** when the **Node / Agent** control is available. Send a small task first, such as asking Hermes to list the files in its workspace and summarize what it finds.

Actual prepares and supervises this Hermes installation. You do not need a separate Hermes install or an inference credential for Console Agent. Its workspace and conversations are separate from a personal `~/.hermes` installation.

If Agent is unavailable, check that the computer is online, its model is loaded, and your account has access. Availability depends on the deployment and the computer's readiness. See [Chat](/docs/chat) for the shared conversation controls.

## Connect your own Hermes installation

1. Install Hermes using the [official installation guide](https://hermes-agent.nousresearch.com/docs/getting-started/installation/).
2. Create an Actual inference credential in [User > Keys](/user/keys). See [API Credentials](/docs/api-keys).
3. Run `hermes model` in your terminal. Choose **Actual Computer**, enter your credential, and select the model you intend to use. Use the exact model identifier reported by Actual.
4. Start a new conversation with `hermes`. Ask a short question before trying a tool task.

The hosted Actual provider base URL is `https://api.actual.inc/v1`. This is an inference address; it is different from the remote gateway URL used by Desktop.

Hermes stores the model, provider, base URL, and API mode in `~/.hermes/config.yaml`, or the selected profile's configuration. For an existing installation, merge these fields into its `model` section instead of replacing the whole file:

```yaml
model:
  provider: actual
  default: YOUR_MODEL_ID
  base_url: https://api.actual.inc/v1
  api_mode: chat_completions
```

Replace `YOUR_MODEL_ID` with your model's identifier. Keep the credential in Hermes's credential setup or its secret `ACTUAL_API_KEY` entry, rather than adding it to this example. Provider information belongs in `config.yaml`, not shell environment flags. The Actual provider uses Chat Completions for model calls, including titles and compaction routed to Actual.

Run `hermes config get model --json` to inspect the selection. Model changes saved to configuration apply to new conversations; use `/model` inside an existing conversation to change that conversation's model. See [Hermes model configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models/) for profiles and auxiliary model settings.

For a local Actual API instead of the hosted endpoint, follow [Private Relay](/docs/private-relay) for the endpoint and authentication requirements of your mode. This configures inference for your own Hermes; it does not enable the managed Desktop gateway.

## Everyday terminal use

Start with a concrete task and the files or directory it should use. Read tool activity and the resulting changes before relying on the result. Tool access and external integrations depend on the Hermes installation's configuration.

| Command | Use |
| --- | --- |
| `hermes` | Open a terminal conversation. |
| `hermes model` | Configure a provider or choose the default model. |
| `hermes tools` | Configure tools for your own installation. |
| `/help` | See commands available in the current conversation. |
| `/new` | Start a fresh conversation. |
| `/resume` | Choose a saved conversation to continue. |

Use `actual update` to update Actual and its managed Hermes runtime. Use Hermes's own update workflow only for an installation you manage independently.

## Troubleshooting

- If **Actual Computer** is missing from your own Hermes provider picker, update that Hermes installation and run `hermes model` again.
- If authentication fails, check the inference credential in [User > Keys](/user/keys). Signing in to Console does not configure a standalone Hermes credential.
- If no model is available, verify the computer is online and the intended model is loaded. See [API Quickstart](/docs/api-quickstart) to check the same credential and model independently.
- If Hermes reports a context-window error, load a model with at least 64K context. Do not raise a configured context value beyond what the model actually supports.
- If a tool cannot see a file, check which computer and workspace Hermes is using.
- If managed Hermes remains unavailable after the computer and model recover, collect [Logs & Telemetry](/docs/logs-and-telemetry).