Skip to content
Back to search

subzeroclaw

An agent small enough to run anywhere. A minimal agentic runtime in C — ~380 lines, 54KB binary, ~2MB RAM. A skill file + an LLM + a shell loop, no framework.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jmlago--subzeroclaw/badge.svg)](/listings/jmlago--subzeroclaw)

HTML

<a href="/listings/jmlago--subzeroclaw"><img src="/api/listings/jmlago--subzeroclaw/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/genlayerlabs/subzeroclaw
cd subzeroclaw
make                          # builds the 55KB binary in ~0.5s

mkdir -p ~/.subzeroclaw/skills
cat > ~/.subzeroclaw/config << 'EOF'
# SubZeroClaw is designed to run on an unhardcoded router: a consumer key (llmr_,
# minted in the router dashboard) and the router endpoint. The model is not a
# dedicated key — it rides in request_extra as BARE JSON; "policy:auto" lets the
# router pick (author the policy_ir with the unhardcoded-use skill).
api_key  = "llmr_your-unhardcoded-consumer-key"
endpoint = "https://YOUR-UNHARDCODED-ROUTER/v1/chat/completions"
request_extra = {"model":"policy:auto","policy_ir":["policy", "..."]}
EOF

./subzeroclaw "check disk usage and clean tmp if over 80%"

Clone, build, point it at your [unhardcoded](https://github.com/genlayerlabs/unhardcoded) router, run. No daemon to register, no service to start. You need `gcc` to build and `curl` at runtime — everything else is in the box.

> **Degraded standalone mode.** You can instead point `endpoint` at a bare > provider with its own key (e.g. an [OpenRouter](https://openrouter.ai) `sk-or-…` > key and a direct `request_extra = {"model": "minimax/minimax-m2.5"}`). The loop > still runs, but with no routing, prompt-cache affinity, or compaction — context > grows until the provider refuses it. Not a supported standalone mode.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 294 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="logo.svg" alt="SubZeroClaw" width="180">
  3. </p>
  4. # SubZeroClaw
  5. > **WARNING: This software executes arbitrary shell commands with no safety checks, no confirmation prompts, no sandboxing, and no guardrails. The LLM decides what to run and the runtime runs it — `rm -rf /` included. There is nothing between the model's output and your system. If you don't understand what that means, do not use this. This is a bare agentic loop: execute the task, whatever it takes, nothing more, nothing less.**
  6. **A small C runtime for skill-driven agents.**
  7. ```
  8. skill.md + LLM + shell + loop = autonomous agent
  9. ```
  10. Every agentic runtime does the same thing: read a skill, call an LLM, execute tools, loop. SubZeroClaw is that principle written directly in C — no framework, no abstractions, no architecture mimicking a problem that never existed. One executable, one shell tool.
  11. ## What it does
  12. You write a skill as a markdown file. You point SubZeroClaw at it. It calls an LLM, executes tools, loops until done. That's the entire runtime.
  13. ```
  14. ~/.subzeroclaw/skills/monitor.md ← what the agent knows
  15. ~/.subzeroclaw/config ← API key + request_extra (model / routing policy)
  16. ~/.subzeroclaw/logs/<session>.txt ← full I/O trace
  17. ```
  18. The agent reads the skill into its system prompt, receives input, and autonomously calls tools until the task is complete. When context grows, the router signals it and the agent seals the old turns **asynchronously** (append-only, in the background) — it never pauses to compact (see "Routing & compaction via unhardcoded").
  19. ## Decision-model control
  20. Set `decision_extra` to enable a controller that selects prepared shell actions
  21. and their parameters together, asking for generation only when needed. Set
  22. `economy_extra` alongside the capable `request_extra` policy to choose economical
  23. or capable generation in the same controller decision, without a nested routing
  24. call. The runtime has no model names built in.
  25. This mode adds executable agendas, dependencies, optional discovery through
  26. shell, completion checks, and recoverable context selection. See the
  27. [configuration, action contract and limitations](examples/decision-models/README.md).
  28. The original loop described below remains the default when `decision_extra` is unset.
  29. ## Quickstart
  30. ```bash
  31. git clone https://github.com/genlayerlabs/subzeroclaw
  32. cd subzeroclaw
  33. make # builds the 55KB binary in ~0.5s
  34. mkdir -p ~/.subzeroclaw/skills
  35. cat > ~/.subzeroclaw/config << 'EOF'
  36. # SubZeroClaw is designed to run on an unhardcoded router: a consumer key (llmr_,
  37. # minted in the router dashboard) and the router endpoint. The model is not a
  38. # dedicated key — it rides in request_extra as BARE JSON; "policy:auto" lets the
  39. # router pick (author the policy_ir with the unhardcoded-use skill).
  40. api_key = "llmr_your-unhardcoded-consumer-key"
  41. endpoint = "https://YOUR-UNHARDCODED-ROUTER/v1/chat/completions"
  42. request_extra = {"model":"policy:auto","policy_ir":["policy", "..."]}
  43. EOF
  44. ./subzeroclaw "check disk usage and clean tmp if over 80%"
  45. ```
  46. Clone, build, point it at your [unhardcoded](https://github.com/genlayerlabs/unhardcoded) router, run. No daemon to register, no service to start. You need `gcc` to build and `curl` at runtime — everything else is in the box.
  47. > **Degraded standalone mode.** You can instead point `endpoint` at a bare
  48. > provider with its own key (e.g. an [OpenRouter](https://openrouter.ai) `sk-or-…`
  49. > key and a direct `request_extra = {"model": "minimax/minimax-m2.5"}`). The loop
  50. > still runs, but with no routing, prompt-cache affinity, or compaction — context
  51. > grows until the provider refuses it. Not a supported standalone mode.
  52. ## Routing & compaction via unhardcoded
  53. Two things a long agent loop needs — **routing with prompt-cache affinity** and
  54. **context compaction** — were never part of "skill + LLM + shell + loop". They
  55. belong to the substrate, not the agent. So rather than grow that logic in C,
  56. SubZeroClaw points its `endpoint` at [**unhardcoded**](https://github.com/genlayerlabs/unhardcoded)
  57. (MIT, open source) and expresses the behaviour as JSON instead of code:
  58. - **The loop** — `request_extra` carries a routing policy and the model. The
  59. router picks the (provider, model) per call and keeps the conversation pinned
  60. to the peer that already holds its prompt-cache prefix (SubZeroClaw sends a
  61. per-run `session` id for that affinity), e.g.
  62. `{"model":"policy:auto","policy_ir":[ "policy", … cache_hot affinity … ]}`.
  63. - **Compaction** — when the router signals context pressure (an `x_router.compact`
  64. flag on the response), SubZeroClaw fires an append-only seal at the router's
  65. `/v1/compact` **in the background** and keeps taking turns; when the sealed block
  66. lands it splices it in *ahead* of the turns that arrived meanwhile. Compaction is
  67. asynchronous: at most one seal is pending per session, including across user
  68. turns. Snapshots include complete tool-call/result pairs. Failed requests or
  69. empty responses retain history and permit a later retry. Normal EOF cancels
  70. pending work and removes its private temporary files; abrupt process kills do
  71. not guarantee cleanup. The seal routing + how many recent turns to
  72. keep verbatim ride in `SUBZEROCLAW_COMPACT_EXTRA` (the second JSON), e.g.
  73. `{"keep_recent":8,"policy_ir":[ "policy", … cheap summariser … ]}`.
  74. This is SubZeroClaw being *more* itself: the loop, the shell, the skill — on a
  75. substrate that carries everything that was never "skill + LLM + shell + loop".
  76. unhardcoded (MIT) is part of that substrate, on the same footing as the Linux
  77. shell it `popen`s: just as there is no agent without a terminal, there is no
  78. routing, cache, or compaction without the router. The runtime is designed to run
  79. on unhardcoded — point `endpoint` at a bare provider and the HTTP call still
  80. fires, but it is a degraded loop (no routing, no cache, no compaction — context
  81. grows until the provider refuses it), not a supported standalone mode.
  82. ## Why not just use ZeroClaw / OpenClaw?
  83. [ZeroClaw](https://github.com/zeroclaw-labs/zeroclaw) rewrites [OpenClaw](https://github.com/openclaw) in Rust. It's good software — but it inherits the architecture of the thing it's replacing: trait systems, channel adapters, observer patterns, identity formats, security layers. All solutions to problems that exist when you're building a multi-user, multi-channel platform.
  84. If your problem is "run one skill on one Pi", none of that applies. You don't need channel adapters because there's one channel. You don't need a security model because you wrote the skill. You don't need a trait system because there's one provider.
  85. SubZeroClaw doesn't simplify their architecture. It ignores it and writes the loop directly.
  86. | | SubZeroClaw | ZeroClaw | OpenClaw |
  87. |-------------------|--------------|--------------|--------------|
  88. | Language | C | Rust | TypeScript |
  89. | Source | ~550 lines | ~15,000 | ~430,000 |
  90. | Binary | 55 KB | 3.4 MB | 80+ MB |
  91. | RAM (runtime) | ~2 MB | < 5 MB | 80-120 MB |
  92. | Compiles on Pi | 0.5s | OOM | slow |
  93. | Dependencies | curl, unhardcoded | ~100 crates | ~800 npm |
  94. ## Tool
  95. One tool: **shell**. `popen()` any command, stderr merged into stdout.
  96. Since the LLM has a shell, it has `git`, `curl`, `himalaya`, `signal-cli`, `ffmpeg`, `jq`, `khal`, `pass` — whatever you install. For file operations, the model uses `cat`, `tee`, `sed`, etc. No adapters, no integrations. The adapter is the shell.
  97. ## Skills
  98. Drop a `.md` file in `~/.subzeroclaw/skills/`. It becomes part of the system prompt.
  99. ```bash
  100. cat > ~/.subzeroclaw/skills/backup.md << 'EOF'
  101. ## Backup Agent
  102. You monitor /home/pi/data every hour.
  103. - Run `rsync -avz /home/pi/data pi@nas:/backup/`
  104. - If rsync fails, retry 3 times with 30s delay
  105. - Log results to /home/pi/backup.log
  106. EOF
  107. ```
  108. No format spec. No skill registry. No trigger matching. Just plain text the LLM reads.
  109. The skills included in this repo (`skills/`) are just examples to show the format. They reference tools and paths specific to one setup. Don't use them as-is — write your own for your system, your tools, your workflow. The whole point is that a skill is just a markdown file you write in 30 seconds.
  110. ## Build
  111. ```bash
  112. make # builds subzeroclaw
  113. make test # unit tests
  114. make test-integration # executable + loopback provider; requires Python 3, no live LLM
  115. make install # copies to ~/.local/bin/
  116. ```
  117. Requires `libcjson-dev` or uses vendored cJSON automatically.
  118. ## Setup
  119. ```bash
  120. mkdir -p ~/.subzeroclaw/skills
  121. cat > ~/.subzeroclaw/config << 'EOF'
  122. # Against an unhardcoded router (the supported mode): consumer key + endpoint.
  123. api_key = "llmr_your-unhardcoded-consumer-key"
  124. endpoint = "https://YOUR-UNHARDCODED-ROUTER/v1/chat/completions"
  125. # The model rides in request_extra as BARE JSON (no surrounding quotes, no
  126. # backslash-escaping — the parser strips one pair of quotes but does not unescape).
  127. # "policy:auto" lets the router pick; author the policy_ir with the unhardcoded-use
  128. # skill. Direct-provider fallback (degraded): {"model": "minimax/minimax-m2.5"}.
  129. request_extra = {"model":"policy:auto","policy_ir":["policy", "..."]}
  130. EOF
  131. ```
  132. Or just use the `.env.example`:
  133. ```bash
  134. cp .env.example .env
  135. # Edit .env with your real API key
  136. source .env
  137. ```
  138. Environment variables override the config file:
  139. ```
  140. SUBZEROCLAW_API_KEY
  141. SUBZEROCLAW_ENDPOINT
  142. SUBZEROCLAW_REQUEST_EXTRA # the LOOP JSON, merged into every request body. Carries the
  143. # model ({"model":"..."}); against an unhardcoded router it carries
  144. # the routing policy too ({"model":"policy:auto","policy_ir":[...]}).
  145. # On a key collision the override wins.
  146. SUBZEROCLAW_COMPACT_EXTRA # the COMPACTION JSON. When set, an x_router.compact signal triggers
  147. # an async append-only seal at the router's /v1/compact; this carries
  148. # keep_recent + the cheap summariser policy_ir. Unset -> no compaction.
  149. ```
  150. ## Usage
  151. ```bash
  152. # One-shot task
  153. ./subzeroclaw "check disk usage and clean tmp if over 80%"
  154. # Interactive
  155. ./subzeroclaw
  156. ```
  157. ## Running as a service
  158. SubZeroClaw is just the loop — it does not supervise itself. Restart-on-crash,
  159. backoff, and logging belong to your init system, which already does them better
  160. than a bundled supervisor could. Bring your own. A minimal systemd unit:
  161. ```ini
  162. [Service]
  163. ExecStart=/usr/local/bin/subzeroclaw "run the backup skill"
  164. Restart=on-failure
  165. RestartSec=5
  166. User=subzero
  167. EnvironmentFile=/etc/subzeroclaw.env # root-owned, chmod 600: SUBZEROCLAW_API_KEY=...
  168. ```
  169. This also gets you credential isolation for free, and it is the recommended way
  170. to hold the key: run the agent as an unprivileged `User=`, and deliver the key
  171. through the environment from a root-owned `EnvironmentFile` the agent's user
  172. cannot read. SubZeroClaw scrubs the provider secrets (`SUBZEROCLAW_API_KEY`,
  173. `_ENDPOINT`, `_REQUEST_EXTRA`, `_COMPACT_EXTRA`) from its own environment right
  174. after reading config (see `config_load`; non-secret vars like `SUBZEROCLAW_SKILLS`
  175. are kept), so the shell it hands the model never
  176. inherits the key — `echo $SUBZEROCLAW_API_KEY` and `cat /proc/self/environ` come
  177. up empty. The supervisor owns the secret; the agent only ever holds a copy in
  178. memory. (None of this constrains what the shell can *do* — that is still
  179. unguarded by design; it only keeps the runtime's own credential out of it.)
  180. ## Session logging
  181. Every session gets a random hex ID. All input, output, tool calls, and results are logged to `~/.subzeroclaw/logs/<session>.txt` with timestamps.
  182. ```
  183. === f850c58ddd4ae72a Sun Feb 16 16:30:01 2026
  184. [2026-02-16 16:30:01] USER: check disk usage
  185. [2026-02-16 16:30:03] TOOL: shell
  186. [2026-02-16 16:30:03] RES: /dev/sda1 72% /
  187. [2026-02-16 16:30:04] ASST: Disk usage is at 72%, below threshold.
  188. ```
  189. ## Config reference
  190. | Key | Default | Description |
  191. |-----|---------|-------------|
  192. | `api_key` | (required) | The unhardcoded router consumer key (`llmr_…`); an OpenRouter/provider key works in the degraded standalone mode |
  193. | `request_extra` | (none) | the loop JSON merged into every request body — carries the `model`, and against an unhardcoded router the routing `policy_ir` |
  194. | `decision_extra` | (none) | Enables typed decision control; JSON sent with state/questions to `/v1/decisions` |
  195. | `economy_extra` | (none) | Optional economical `policy_ir`; controller chooses it or capable `request_extra` in one decision |
  196. | `decision_context_bytes` | 18000 | Selection threshold in decision mode, 4096–24000 bytes |
  197. | `compact_extra` | (none) | the compaction JSON — `keep_recent` + the cheap summariser `policy_ir`; unset disables compaction |
  198. | `endpoint` | `https://openrouter.ai/api/v1/chat/completions` | API endpoint (point it at an unhardcoded router for routing/cache/compaction) |
  199. | `skills_dir` | `~/.subzeroclaw/skills` | Path to skill markdown files |
  200. | `log_dir` | `~/.subzeroclaw/logs` | Session log directory |
  201. | `max_turns` | 200 | Max tool-call loops per input |
  202. ## Troubleshooting
  203. | Symptom | Fix |
  204. |---------|-----|
  205. | `curl: command not found` or no response from the model | The runtime shells out to `curl` for API calls. Install it: `sudo apt install curl`. |
  206. | `401 Unauthorized` from the endpoint | Missing or invalid key. Check `api_key` in `~/.subzeroclaw/config` or the `SUBZEROCLAW_API_KEY` env var. |
  207. | Model never calls tools / loops without progress | Use a model that supports tool calling (set it in `request_extra`) — not every model does. |
  208. | `make` fails on a fresh Pi | Install a compiler: `sudo apt install build-essential`. The vendored cJSON is used automatically when `libcjson-dev` is absent. |
  209. ## Source
  210. ```
  211. src/
  212. ├── subzeroclaw.c Transport, shell and generative loop
  213. ├── decision.h Typed controller and context selection
  214. ├── test.c the test suite
  215. ├── cJSON.c Vendored JSON parser
  216. └── cJSON.h
  217. ```
  218. ## Philosophy
  219. SubZeroClaw is an anti-framework. It does one thing: connect an LLM to a shell and loop. That's it. No plugin system, no middleware, no lifecycle hooks, no dependency injection. Just the loop.
  220. This follows the Unix philosophy — do one thing and do it well. `grep` searches text. `curl` fetches URLs. `subzeroclaw` runs an agentic loop. It doesn't need to know about git, email, HTTP, or filesystems because the tools that already do those things are one `popen()` away. The model calls `git` the same way you do. The entire system is the integration layer.
  221. Every layer of "framework" between the model and the shell is complexity that adds nothing. If the model can run `git`, why build a git adapter? If it can run `curl`, why build an HTTP tool? If it can run `tee`, why build a file-writing abstraction? Frameworks grow because they solve problems that emerge from their own architecture — channel routing because they support multiple channels, plugin registries because they have plugins, security models because they run untrusted code. SubZeroClaw has none of these problems because it doesn't have any of these features. One agent, one skill, one device. The code that remains is the code that can't be removed.
  222. OpenClaw solved the agentic loop with 430,000 lines of TypeScript. ZeroClaw re-solved it with 15,000 lines of Rust. Both are good — but both carry the weight of problems that only exist at platform scale: multi-tenancy, channel routing, identity portability, plugin registries.
  223. SubZeroClaw asks: what if the problem is just "one agent, one skill, one device"?
  224. ## License
  225. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.