File size: 7,471 Bytes
674d56a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 | ---
title: "Actual Setup — Set up Actual Computer (actual.inc) inference in Hermes"
sidebar_label: "Actual Setup"
description: "Set up Actual Computer (actual.inc) inference in Hermes"
---
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
# Actual Setup
Set up Actual Computer (actual.inc) inference in Hermes.
## Skill metadata
| | |
|---|---|
| Source | Optional — install with `hermes skills install official/devops/actual-setup` |
| Path | `optional-skills/devops\actual-setup` |
| Version | `2.0.0` |
| Author | shl0ms + Hermes Agent |
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `actual`, `actual-inc`, `provider`, `local-inference`, `relay`, `gguf`, `setup` |
## Reference: full SKILL.md
:::info
The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
:::
# Actual Computer Setup Skill
Sets up [actual.inc](https://actual.inc) (Actual Computer) as a Hermes inference
provider. Actual turns the user's own hardware into a private inference cluster
and exposes an OpenAI-compatible API two ways: a hosted end-to-end-encrypted
relay at `https://api.actual.inc` (authenticated with an `ac_` key), and a local
on-device daemon at `http://127.0.0.1:8080` (no auth on loopback). This skill
does not install the Actual daemon for the user — device authorization requires
a human in a browser.
## When to Use
- User wants to add actual.inc as an inference provider (cloud relay or local).
- User has an `ac_` key and wants Hermes routed through their Actual cluster.
- User wants fully-local, on-device inference via the Actual daemon.
- Troubleshooting: Actual requests failing with cryptic 400s or empty streams.
## Prerequisites
- Hermes has **first-class `actual` provider support** (provider id `actual`,
aliases `actual-computer`, `actualcomputer`, `aci`). Do NOT configure Actual
as a `custom_providers` / `providers.actual.*` entry on current Hermes — the
built-in provider owns the name and handles base-url normalization, the
Responses transport, and local no-auth automatically.
- Relay mode: an Actual account and an `ac_` inference key from
https://actual.inc/user/keys.
- Local mode: the user has installed the daemon
(`curl -fsSL "https://actual.inc/install" | bash`) and completed device
authorization by running `actual` once and opening the printed
`https://actual.inc/device?code=...` URL in a browser. Relay that URL to the
user and WAIT — never invent an email or authorize on their behalf. Codes
expire in 5 minutes; re-run `actual` for a fresh one.
## How to Run
### Relay / API mode
1. Put the key in `.env` (secrets only — never config.yaml):
append `ACTUAL_API_KEY=ac_...` to `~/.hermes/.env`.
2. Verify the key and discover models with `terminal`:
```bash
curl -s https://api.actual.inc/v1/models -H "Authorization: Bearer $ACTUAL_API_KEY"
```
3. Select provider + model:
```bash
hermes config set model.provider actual
hermes config set model.default "MODEL_ID_FROM_DISCOVERY"
```
4. Verify end-to-end:
```bash
hermes chat -Q -q "Reply with exactly: ACTUAL_OK" --provider actual -m MODEL_ID
```
### Local mode
1. Human has installed + authorized the daemon (see Prerequisites).
2. Download and load a model (scriptable once authorized):
```bash
actual models search "qwen2.5 0.5b instruct gguf" --limit 8 --no-prompt
# Downloads REQUIRE an explicit quantization (409 ambiguous_model_download otherwise):
actual models download "Qwen/Qwen2.5-0.5B-Instruct-GGUF/Q4_K_M"
actual models list # note the INSTALLED name (differs from download id)
actual models load "qwen2.5-0.5b-instruct-q4_k_m" # load by installed name
```
3. Point Hermes at the daemon. `ACTUAL_BASE_URL` with a loopback host flips the
built-in provider into local no-auth mode automatically — no key needed:
append `ACTUAL_BASE_URL=http://127.0.0.1:8080` to `~/.hermes/.env`, then:
```bash
hermes config set model.provider actual
hermes config set model.default "INSTALLED_MODEL_NAME"
```
4. Verify (reduced toolset — see context-window pitfall below):
```bash
hermes chat -Q -q "Reply with exactly: LOCAL_OK" --provider actual -m INSTALLED_NAME -t file,web
```
## Quick Reference
| Thing | Value |
|---|---|
| Hosted relay | `https://api.actual.inc/v1` (normalized from bare host automatically) |
| Local daemon | `http://127.0.0.1:8080/v1` (no auth on loopback) |
| Key env var | `ACTUAL_API_KEY` (`ac_...`) |
| Base URL env var | `ACTUAL_BASE_URL` (loopback host ⇒ local no-auth mode) |
| Provider id / aliases | `actual` / `actual-computer`, `actualcomputer`, `aci` |
| Transport | Responses API (`codex_responses`) — built-in, do not override |
| Cluster pinning | `X-Cluster-ID` header via `providers.actual.extra_headers` in config.yaml |
| Model size guide | 0.5B Q4_K_M ~470MB (toy), 7-8B Q4_K_M ~4.5GB (daily driver), 32B ~20GB |
## Pitfalls
1. **reasoning_effort trap (handled by Hermes since the first-class provider).**
Actual's SGLang/vLLM backends accept only `none/low/medium/high/max`;
`xhigh`/`ultra` used to fail with a cryptic
`Expecting value: line 1 column 1 (char 0)` (a wrapped HTTP 400). The
built-in provider clamps `xhigh→high` and `ultra→max` on the wire. If a
request still 400s this way on an old Hermes, set a per-model cap:
`agent.reasoning_overrides.<model>: high` in config.yaml.
2. **Context-window overflow on small local models.** Hermes' default toolset
is ~26k tokens of schemas plus a ~9k-token system prompt. A model loaded
with a 32k context overflows before the first turn, and llama.cpp-family
servers emit a bare `data: [DONE]` — Hermes reports
`Provider returned an empty stream with no finish_reason`. This is NOT an
SSE bug. Fixes: restrict tools (`-t file,web`), load the model with a
larger `n_ctx`, or pick a >=64k-context model for the full toolset.
Upstream tracking: #51448 (do not file new issues; add evidence there).
Related but distinct: #65631 (HTTP-200 SSE carrying a 400), #56516
(reasoning-only streams).
3. **Download ids vs installed names.** `actual models download` takes
`repo/QUANT` and 409s without an explicit quantization;
`actual models load` takes the INSTALLED name from `actual models list`.
4. **Reasoning models returning empty content.** GLM/Qwen reasoning variants
emit thinking in a separate `reasoning` field and can burn a small
output budget entirely on reasoning. Check the server-side output default
before assuming failure.
5. **Do not create a custom provider named `actual`.** Older setup guides
(pre first-class support) wrote `providers.actual.*` config blocks. On
current Hermes the built-in provider wins the name; stale custom blocks
are ignored or conflict. Remove them and use the env vars + model.provider
flow above.
## Verification
```bash
# Relay:
hermes chat -Q -q "Reply with exactly: ACTUAL_OK" --provider actual -m MODEL
# Local (small model — reduced toolset):
hermes chat -Q -q "Reply with exactly: LOCAL_OK" --provider actual -m MODEL -t file,web
# Provider status (local no-auth shows key_source=local-offline):
hermes status
```
For other OpenAI-compatible clients (e.g. OpenCode), see
`references/opencode.md`.
|