Actual Setup

Set up Actual Computer (actual.inc) inference in Noora.

Skill metadata

Source	Optional — install with noora skills install official/devops/actual-setup
Path	optional-skills/devops/actual-setup
Version	2.0.0
Author	shl0ms + Noora 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 Noora 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 (Actual Computer) as a Noora 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 Noora 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

• Noora 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 Noora — 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 ~/.noora/.env.
2. Verify the key and discover models with terminal:

   curl -s https://api.actual.inc/v1/models -H "Authorization: Bearer $ACTUAL_API_KEY"

3. Select provider + model:

   noora config set model.provider actual
   noora config set model.default "MODEL_ID_FROM_DISCOVERY"

4. Verify end-to-end:

   noora 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):

   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 Noora 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 ~/.noora/.env, then:

   noora config set model.provider actual
   noora config set model.default "INSTALLED_MODEL_NAME"

4. Verify (reduced toolset — see context-window pitfall below):

   noora 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 Noora 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 Noora, set a per-model cap: agent.reasoning_overrides.<model>: high in config.yaml.
2. Context-window overflow on small local models. Noora' 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] — Noora 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 max_tokens entirely on reasoning. Give generous max_tokens 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 Noora 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

# Relay:
noora chat -Q -q "Reply with exactly: ACTUAL_OK" --provider actual -m MODEL
# Local (small model — reduced toolset):
noora 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):
noora status

For other OpenAI-compatible clients (e.g. OpenCode), see references/opencode.md.