An architecture guide explaining how the runtime applies permissions, workspace access, memory scope, and log attribution to each agent. It focuses on how the system enforces these rules internally.

Use it to inspect per-agent security boundaries, control access to sibling workspaces, understand unrestricted filesystem access, and trace agent activity.

It helps you understand why an agent can or cannot read, write, or access another agent's files. This is useful when configuring isolation and diagnosing permission behavior.

internals — Agent for coding agents by zeroclaw-labs: An architecture guide explaining how the runtime applies permissions…

About the project

ZeroClaw is a Rust-based runtime for running a personal AI assistant on a user's own machine, with connections to language-model providers, communication channels, and external tools. It is for people who want to operate an assistant across channels such as Discord, Telegram, email, voice, webhooks, or a command line while keeping control of its data and credentials. The catalogue add-ons provide workflows and agents for using ZeroClaw.

zeroclaw-labs/zeroclaw · 32,731 stars · on GitHub

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add agents/zeroclaw-labs/zeroclaw/internals

Clone the repo

git clone --depth 1 https://github.com/zeroclaw-labs/zeroclaw

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/agents/zeroclaw-labs/zeroclaw/internals.svg)](https://agentmods.dev/agents/zeroclaw-labs/zeroclaw/internals)

Your own site

<a href="https://agentmods.dev/agents/zeroclaw-labs/zeroclaw/internals"><img src="https://agentmods.dev/badge/agents/zeroclaw-labs/zeroclaw/internals.svg" alt="Measured on agentmods" height="20"></a>

Per session 0 Only the description is in the session, so the agent can decide to use it. The body loads when it is invoked.

When invoked 1,038 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.00000	$0.01038
Opus 5	$0.00000	$0.00519
Sonnet 5	$0.00000	$0.00208
Haiku 4.5	$0.00000	$0.00104

Measured 5d ago against content hash 313b4c8f5bb1, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

internals scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 5d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

docs/book/src/agents/internals.md · 52 lines

How it starts

The opening of the file, as written. The whole thing — 52 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Runtime internals

This page is the architecture-depth companion to the rest of the Agents section: how the runtime enforces per-agent permissions, scopes memory, and attributes logs. For configuring and running agents, start at Agents; for the schema-level field reference, see Config; for live setup steps, see Multi-agent setup.

Permissions model

Each agent's effective SecurityPolicy is built by SecurityPolicy::for_agent(config, alias):

Start from the agent's risk profile ([risk_profiles.<profile>]).
Set the boundary to the per-agent workspace dir (<install>/agents/<alias>/workspace/).
Walk [agents.<alias>.workspace.access]:
- Read → sibling's workspace lands in the read-only allowlist.
- Write / ReadWrite → sibling's workspace lands in the read-write allowlist.
If [agents.<alias>.workspace.unrestricted_filesystem] is true, flip workspace_only off.

The read-only allowlist is honored by file_read (and other read-side tools); the read-write allowlist gates file_write, file_edit, git_operations, and the shell tool's path-touching invocations. POSIX device files (/dev/null, /dev/zero, /dev/random, /dev/urandom) are always readable so shell idioms keep working without per-agent config.

SubAgent spawns enforce the rule that a child cannot escalate beyond its parent. The validator's full axis list and the budget-sharing behavior are documented at Delegation → Permission inheritance.

Memory model

Each agent has its own Arc<dyn Memory> instance. The factory (zeroclaw_memory::create_memory_for_agent) dispatches by backend kind:

SQLite / Postgres / Lucid: shared install-wide store. The agents table maps alias → UUID, and the memories table carries agent_id referencing that UUID. The factory wraps the inner backend in AgentScopedMemory, which stamps the bound agent's UUID on every store via store_with_agent and filters every recall via recall_for_agents with the resolved allowlist.
Markdown: per-agent dir. Each agent's MarkdownMemory writes to <install>/agents/<alias>/workspace/MEMORY.md and memory/YYYY-MM-DD.md. Cross-agent recall is composed by AgentScopedMarkdownMemory, which holds the bound agent's MarkdownMemory plus a peer set of (alias, MarkdownMemory) pairs and unions their results with [<alias>] attribution prefixes on each row.
Qdrant: shared collection, payload-keyed. The agent_id payload field is the per-agent attribution; recall_for_agents over-fetches and post-filters by payload.
None: no-op stub. The wrapper still exists so the runtime path is uniform.

Read the full file on GitHub · 52 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

5d ago First seen · 52 lines · 0 tokens per session scan A 313b4c8f5bb1

Subscribe to this mod's changes

internals is an agent published in the GitHub repository zeroclaw-labs/zeroclaw (32,731 stars, last pushed today), licensed Apache-2.0. It costs nothing until one of its globs matches a file; then it loads 1,038 tokens. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Building agents agent agentic ai infra ml openclaw

comparator

Compare two outputs WITHOUT knowing which skill produced them.

bytedance/deer-flow · 0 tokens

implementer

Milestone executor. Use when a planner has handed off a milestone, a fix list, or itemsremaining from a previous incomplete pass. Codes, tests, repairs. Returns what's done, what's remaining, and a completion score. Never replans, never judges.

ai-driven-dev/framework · 55 tokens

planner

Planning agent. Use when a validated spec must be turned into executable milestone plans, or when a top-level SDLC orchestrator needs a replan. Writes plans and decisions only. Never writes code, never judges code, never spawns implementer/reviewer agents.