subzeroclaw-use

name

subzeroclaw-use

description

Run and operate SubZeroClaw — the ~550-line C agentic daemon (skill.md + LLM + shell + loop). Load this to build it, configure it (~/.subzeroclaw/config), write an agent skill, run a task, wire it to an unhardcoded router for routing/cache/compaction, or run it as a systemd service with credential isolation. WARNING: it executes arbitrary shell with no sandbox. To develop the runtime itself, use subzeroclaw-contribute.

Using SubZeroClaw

Read the warning first. SubZeroClaw runs whatever the model emits through popen() — no confirmation, no sandbox, rm -rf / included. There is nothing between the model's output and your system. Run it only where you accept that, ideally as an unprivileged service user (see As a service).

The whole runtime is: read a skill (markdown) → call an LLM → run shell tools → loop until done. One tool: shell. The "adapter" for git/curl/email/ffmpeg is that they're one popen() away — install the CLI, the model uses it.

Two senses of "skill" — don't conflate them. A SubZeroClaw skill is a plain .md file in ~/.subzeroclaw/skills/ that becomes the agent's system prompt (what the agent knows). This file is a Claude Code skill (how to operate the tool). When the docs below say "write a skill", they mean the former.

Build & run

git clone https://github.com/genlayerlabs/subzeroclaw && cd subzeroclaw
make                                   # ~0.5s → the 55KB binary (needs gcc; curl at runtime)
mkdir -p ~/.subzeroclaw/skills
# ...write ~/.subzeroclaw/config (below) and a skill .md...
./subzeroclaw "check disk usage and clean tmp if over 80%"   # one-shot
./subzeroclaw                                                 # interactive
make install                           # → ~/.local/bin/

An agent skill is just prose the LLM reads — no format, no registry, no trigger matching. Drop a .md in ~/.subzeroclaw/skills/ and it joins the system prompt. The repo's skills/*.md are format examples tied to one setup; write your own.

Configuration (~/.subzeroclaw/config)

These are the only keys the runtime parses (config_parse_line); config.example is the canonical template.

Key	Meaning
api_key	The unhardcoded router consumer key (llmr_…) — SubZeroClaw is designed to run on the router. A bare OpenRouter/provider key also works but is a degraded loop. Required.
request_extra	JSON merged into every request body. Carries the model ({"model":"..."}) — there is no dedicated model key. Against a router it also carries the routing policy_ir. Override wins on key collision.
compact_extra	JSON enabling async compaction: keep_recent + a cheap summariser policy_ir. Unset → no compaction.
endpoint	default OpenRouter; point at an unhardcoded router for routing/cache/compaction.
skills_dir, log_dir	defaults under ~/.subzeroclaw/.
max_turns	tool-call loops per input (default 200).

Env vars SUBZEROCLAW_API_KEY, SUBZEROCLAW_ENDPOINT, SUBZEROCLAW_REQUEST_EXTRA, SUBZEROCLAW_COMPACT_EXTRA override the file.

The unhardcoded substrate (routing + compaction)

Routing with prompt-cache affinity and context compaction are not part of "skill + LLM + shell + loop" — they live in the substrate. Point endpoint at an unhardcoded router and express them as JSON:

• Routing: request_extra = {"model":"policy:auto","policy_ir":[ … ]}. The runtime sends a per-run session id so the router keeps the conversation on its cache-hot peer. (Author the policy_ir with the unhardcoded-use skill.)
• Compaction: on an x_router.compact signal, the runtime fires an append-only seal at the router's /v1/compact in the background and keeps taking turns, splicing the sealed block in ahead of the turns that arrived meanwhile — no pause, the cache prefix is never rewritten. compact_extra carries keep_recent + the summariser policy.

Pointed at a bare provider the HTTP call still fires, but it's a degraded loop (no routing, cache, or compaction) — not a supported standalone mode.

As a service (and credential isolation)

SubZeroClaw doesn't supervise itself — bring your init system. A systemd unit with Restart=on-failure and an EnvironmentFile (root-owned, chmod 600) holding SUBZEROCLAW_API_KEY gets you restart + credential isolation. The runtime scrubs the four provider secrets (SUBZEROCLAW_API_KEY, _ENDPOINT, _REQUEST_EXTRA, _COMPACT_EXTRA) from its own environment right after config_load — wiping the value in place, then unsetenv — so the shell it hands the model never inherits the key (cat /proc/self/environ comes up empty). Non-secret vars like SUBZEROCLAW_SKILLS are deliberately kept (the genswarms wrapper sets it). The supervisor owns the secret; the shell stays unguarded by design — the scrub only keeps the runtime's own secrets out of it.

Gotchas

• A top-level model = line in the config is ignored — the runtime never parses it. The model rides in request_extra. (This is the most common misconfiguration.)
• Use a tool-calling model. If the model can't call tools it will loop without progress. Set it in request_extra.
• curl is required at runtime (API calls shell out to it); gcc only to build.
• Compaction is opt-in: unset compact_extra → context grows until the provider refuses it.

Where to read more

• README.md — the full config reference, session logging, troubleshooting table.
• config.example — the canonical config template.
• The unhardcoded-use / sigma-policy-author skills — author the routing and summariser policy_ir this runtime sends.