actual-setup

1---2name: actual-setup3description: Set up Actual Computer (actual.inc) inference in Hermes.4version: 2.0.05author: shl0ms + Hermes Agent6license: MIT7platforms: [linux, macos, windows]8metadata:9  hermes:10    tags: [actual, actual-inc, provider, local-inference, relay, gguf, setup]11    category: devops12---13 14# Actual Computer Setup Skill15 16Sets up [actual.inc](https://actual.inc) (Actual Computer) as a Hermes inference17provider. Actual turns the user's own hardware into a private inference cluster18and exposes an OpenAI-compatible API two ways: a hosted end-to-end-encrypted19relay at `https://api.actual.inc` (authenticated with an `ac_` key), and a local20on-device daemon at `http://127.0.0.1:8080` (no auth on loopback). This skill21does not install the Actual daemon for the user — device authorization requires22a human in a browser.23 24## When to Use25 26- User wants to add actual.inc as an inference provider (cloud relay or local).27- User has an `ac_` key and wants Hermes routed through their Actual cluster.28- User wants fully-local, on-device inference via the Actual daemon.29- Troubleshooting: Actual requests failing with cryptic 400s or empty streams.30 31## Prerequisites32 33- Hermes has **first-class `actual` provider support** (provider id `actual`,34  aliases `actual-computer`, `actualcomputer`, `aci`). Do NOT configure Actual35  as a `custom_providers` / `providers.actual.*` entry on current Hermes — the36  built-in provider owns the name and handles base-url normalization, the37  Responses transport, and local no-auth automatically.38- Relay mode: an Actual account and an `ac_` inference key from39  https://actual.inc/user/keys.40- Local mode: the user has installed the daemon41  (`curl -fsSL "https://actual.inc/install" | bash`) and completed device42  authorization by running `actual` once and opening the printed43  `https://actual.inc/device?code=...` URL in a browser. Relay that URL to the44  user and WAIT — never invent an email or authorize on their behalf. Codes45  expire in 5 minutes; re-run `actual` for a fresh one.46 47## How to Run48 49### Relay / API mode50 511. Put the key in `.env` (secrets only — never config.yaml):52   append `ACTUAL_API_KEY=ac_...` to `~/.hermes/.env`.532. Verify the key and discover models with `terminal`:54   ```bash55   curl -s https://api.actual.inc/v1/models -H "Authorization: Bearer $ACTUAL_API_KEY"56   ```573. Select provider + model:58   ```bash59   hermes config set model.provider actual60   hermes config set model.default "MODEL_ID_FROM_DISCOVERY"61   ```624. Verify end-to-end:63   ```bash64   hermes chat -Q -q "Reply with exactly: ACTUAL_OK" --provider actual -m MODEL_ID65   ```66 67### Local mode68 691. Human has installed + authorized the daemon (see Prerequisites).702. Download and load a model (scriptable once authorized):71   ```bash72   actual models search "qwen2.5 0.5b instruct gguf" --limit 8 --no-prompt73   # Downloads REQUIRE an explicit quantization (409 ambiguous_model_download otherwise):74   actual models download "Qwen/Qwen2.5-0.5B-Instruct-GGUF/Q4_K_M"75   actual models list        # note the INSTALLED name (differs from download id)76   actual models load "qwen2.5-0.5b-instruct-q4_k_m"   # load by installed name77   ```783. Point Hermes at the daemon. `ACTUAL_BASE_URL` with a loopback host flips the79   built-in provider into local no-auth mode automatically — no key needed:80   append `ACTUAL_BASE_URL=http://127.0.0.1:8080` to `~/.hermes/.env`, then:81   ```bash82   hermes config set model.provider actual83   hermes config set model.default "INSTALLED_MODEL_NAME"84   ```854. Verify (reduced toolset — see context-window pitfall below):86   ```bash87   hermes chat -Q -q "Reply with exactly: LOCAL_OK" --provider actual -m INSTALLED_NAME -t file,web88   ```89 90## Quick Reference91 92| Thing | Value |93|---|---|94| Hosted relay | `https://api.actual.inc/v1` (normalized from bare host automatically) |95| Local daemon | `http://127.0.0.1:8080/v1` (no auth on loopback) |96| Key env var | `ACTUAL_API_KEY` (`ac_...`) |97| Base URL env var | `ACTUAL_BASE_URL` (loopback host ⇒ local no-auth mode) |98| Provider id / aliases | `actual` / `actual-computer`, `actualcomputer`, `aci` |99| Transport | Responses API (`codex_responses`) — built-in, do not override |100| Cluster pinning | `X-Cluster-ID` header via `providers.actual.extra_headers` in config.yaml |101| Model size guide | 0.5B Q4_K_M ~470MB (toy), 7-8B Q4_K_M ~4.5GB (daily driver), 32B ~20GB |102 103## Pitfalls104 1051. **reasoning_effort trap (handled by Hermes since the first-class provider).**106   Actual's SGLang/vLLM backends accept only `none/low/medium/high/max`;107   `xhigh`/`ultra` used to fail with a cryptic108   `Expecting value: line 1 column 1 (char 0)` (a wrapped HTTP 400). The109   built-in provider clamps `xhigh→high` and `ultra→max` on the wire. If a110   request still 400s this way on an old Hermes, set a per-model cap:111   `agent.reasoning_overrides.<model>: high` in config.yaml.1122. **Context-window overflow on small local models.** Hermes' default toolset113   is ~26k tokens of schemas plus a ~9k-token system prompt. A model loaded114   with a 32k context overflows before the first turn, and llama.cpp-family115   servers emit a bare `data: [DONE]` — Hermes reports116   `Provider returned an empty stream with no finish_reason`. This is NOT an117   SSE bug. Fixes: restrict tools (`-t file,web`), load the model with a118   larger `n_ctx`, or pick a >=64k-context model for the full toolset.119   Upstream tracking: #51448 (do not file new issues; add evidence there).120   Related but distinct: #65631 (HTTP-200 SSE carrying a 400), #56516121   (reasoning-only streams).1223. **Download ids vs installed names.** `actual models download` takes123   `repo/QUANT` and 409s without an explicit quantization;124   `actual models load` takes the INSTALLED name from `actual models list`.1254. **Reasoning models returning empty content.** GLM/Qwen reasoning variants126   emit thinking in a separate `reasoning` field and can burn a small127   `max_tokens` entirely on reasoning. Give generous max_tokens before128   assuming failure.1295. **Do not create a custom provider named `actual`.** Older setup guides130   (pre first-class support) wrote `providers.actual.*` config blocks. On131   current Hermes the built-in provider wins the name; stale custom blocks132   are ignored or conflict. Remove them and use the env vars + model.provider133   flow above.134 135## Verification136 137```bash138# Relay:139hermes chat -Q -q "Reply with exactly: ACTUAL_OK" --provider actual -m MODEL140# Local (small model — reduced toolset):141hermes chat -Q -q "Reply with exactly: LOCAL_OK" --provider actual -m MODEL -t file,web142# Provider status (local no-auth shows key_source=local-offline):143hermes status144```145 146For other OpenAI-compatible clients (e.g. OpenCode), see147`references/opencode.md`.148