Use Actual

Hermes

Use managed Hermes or connect your own terminal agent to Actual

4 min readMarkdown6 sectionsopen computers →

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, 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	The selected Actual computer's managed workspace.	An online Actual computer and a loaded model.
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 to install Actual, authorize your computer, and download and load a model. 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, 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 for the shared conversation controls.

Connect your own Hermes installation#

Install Hermes using the official installation guide.
Create an Actual inference credential in User > Keys. See API Credentials.
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.
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:

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 for profiles and auxiliary model settings.

For a local Actual API instead of the hosted endpoint, follow 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. 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 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.