An AI agent that has to ask first
StarClaw is an open-source AI agent that writes and runs its own code, but every action it takes is checked against a policy you control, risky ones are put to a human, and everything is written to a signed log.
Status: alpha. The latest version on npm is 2.0.0-alpha.3. The source on GitHub is a little ahead (2.0.0-alpha.5, unreleased). It is tested on Windows 11 with Node.js 25.9.0 only. It does not stop prompt injection. Read the security page before you try it.
Who it is for
Developers who are comfortable with a command line and Node.js, and who want to try an agent that is built around limits and records. It is not a finished product for customers. The project itself says it is "not yet recommended for customers".
Quick start
Three steps, taken from the project README. You need Node.js 25.9.0 or newer.
-
Install the alpha and set a model key. The bundled model backend is Groq; the model is an interface, so you can bring your own.
Plainnpm install starclaw@next export GROQ_API_KEY=...npm install starclawgives the old 1.0.0 package, which is deprecated and broken. Do not use it. -
Write the default policy. It is conservative.
npx starclaw policy init -
Give it a goal.
npx starclaw run "summarise the headlines on https://example.com"
With the default policy, StarClaw asks you before it runs code, writes a file, uses the network, saves memory, saves a skill or spends money. The only thing it does silently is read files inside ./workspace. If nobody can answer (no terminal, or --non-interactive), anything that needs approval is denied.
Optional but recommended: npx starclaw sandbox build builds the Docker sandbox image (needs Docker), and npx starclaw doctor tests each isolation layer on your machine and tells you which one is active and why.
See it work in two minutes, offline
git clone https://github.com/mnemopay/starclaw && cd starclaw && npm install && npm run build
node dist/cli.js sandbox build # needs Docker
npm run demo # no API key, no network, no real money
A scripted model plays an agent that obeys instructions hidden in a web page. You watch StarClaw stop it from leaking data and from paying an attacker, even though the policy allows web access and spending. Then the demo checks the signed log, edits one record, and shows the check fail.
What is real: the sandbox, the policy engine (the Governor), taint tracking, the approval flow and the audit log. What is fake: the language model (a script) and the payment rail (a counter). So the demo does not prove that a real model cannot be steered. It can. Without Docker the demo still runs, using only the Node permission layer.
What it does
- A governed agent. You give a goal. A language model writes JavaScript. StarClaw runs it, and every file, network or spending request goes through a policy that can allow, ask a human, or deny. Invalid policy files make it refuse to start.
- Layered sandbox. Generated code runs in a locked-down Docker container (no network, read-only, no capabilities, no mounts) with Node's permission model inside. Without Docker it uses the Node permission model alone, which the docs call a "seat belt", not a VM. At startup each layer is tested; if the chosen layer fails its test, StarClaw refuses to run generated code.
- Approval channels. Terminal, Telegram, Slack, Discord and an HTTP API. Only the owner can approve (by owner id on Telegram, Slack and Discord; by bearer key on HTTP). A timeout, an error, or any answer other than an exact approval counts as a denial. Slack and Discord are off by default and have been tested only against local fakes, not the real services.
- Taint tracking. Content from the web or from other people marks the session as tainted. While tainted, running commands, network access, spending and saving skills can never be auto-allowed. A human has to approve, and is shown where the untrusted content came from. This is coarse and incomplete; see the security page.
- Signed, tamper-evident audit log. Each record is hash-chained and Ed25519-signed, and written before the action runs.
starclaw audit verifychecks it offline and detects edits, deletions, reordering and truncation. Anyone who can read the signing key can forge the log. - Scheduler. Unattended jobs, including "heartbeat" jobs that message you only if something needs attention. They run only while
starclaw daemonis running. Unattended runs cannot run host commands, and an approval request nobody answers is a denial. - Governed browser tools. Off by default. They drive the MnemoPay Native Browser through its control API, limited to domains you list. Opening a tab always needs a human. Tested only against a fake of that API, not the real browser.
- Spend caps. Per-action and total caps, in whole cents, enforced outside the generated code. A human approving an amount cannot push it past the cap. Default caps are 0. No payment rail ships, so real payments are not implemented and not tested.
More detail, including what each piece does not cover, is on the security page and in the docs.