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`.