Glossary

Key terms used throughout Scarab-Runtime documentation.

agentd The central daemon process that manages agent lifecycles, enforces sandboxing, dispatches tool calls, and maintains all persistent stores. Agents communicate with agentd over a Unix domain socket using the libagent IPC protocol.

Agent An autonomous process that follows the Plan → Act → Observe lifecycle loop. An agent is spawned from a manifest, holds a set of capabilities, and interacts with the world exclusively through tool invocations.

Agent Store agentd's persistent registry of installed agent definitions. Operators install agents with ash agent install and spawn them by name with ash agent run.

ash The Scarab-Runtime command-line shell. The primary operator interface to agentd, used to spawn agents, inspect state, manage secrets, query logs, and more.

Audit log A tamper-evident append-only record of significant events in agentd: agent spawns, tool invocations, state transitions, secret uses, and operator actions. Queried with ash audit.

Blackboard A daemon-global shared key-value store. Any agent with bb.read/bb.write capabilities can read and write it. Useful for inter-agent communication and shared state. Values are JSON and support TTLs and compare-and-swap.

Capability A declarative permission token in the format <domain>.<action>[:<scope>]. Capabilities are declared in a manifest and enforced at every tool invocation. Example: fs.write:/home/agent/**.

Capability grant A runtime extension of an agent's capabilities, issued by a supervisor agent. Grants allow temporary or narrowly-scoped permissions beyond what the manifest declares. Revocable at any time.

cgroups v2 Linux Control Groups version 2. Used by agentd to enforce per-agent resource limits (memory_limit, cpu_shares, max_open_files).

HITL (Human-in-the-Loop) A workflow pattern where an agent's tool request is held in a pending queue until a human operator approves or denies it. Used for sensitive operations. Managed with ash pending, ash approve, and ash deny.

IPC (Inter-Process Communication) The protocol between agents and agentd. Uses JSON-encoded messages framed with a 4-byte length prefix, transported over a Unix domain socket.

libagent The Rust SDK library that agent binaries link against. Provides Agent::from_env(), invoke_tool(), observe(), transition(), memory_get(), memory_set(), and more.

Lifecycle states The states an agent transitions through: Init → Plan → Act → Observe → Plan (loop). An agent can transition to Terminate from any state except Init.

Manifest A YAML file declaring an agent's identity, trust level, capabilities, resource limits, network policy, and lifecycle behavior. The apiVersion must be scarab/v1 and kind must be AgentManifest.

MCP (Model Context Protocol) An open standard protocol for AI agents to call tools exposed by external processes or HTTP services. agentd's Phase 8.1 integration allows operators to register MCP servers and attach them to agents.

McpSession An active connection between agentd and an MCP server for a specific agent attachment. Each attachment creates an independent session with its own subprocess or HTTP connection.

Message bus A publish-subscribe system for asynchronous agent-to-agent communication. Agents publish JSON messages to topics; subscribers receive them via a mailbox and drain it with bus.poll.

Namespace (Linux) Linux kernel feature used to isolate agent processes. agentd uses PID, mount, network, IPC, and UTS namespaces to contain each agent.

Observation log A structured, timestamped log of an agent's reasoning, tool calls, and results. Private to each agent (supervisors can query children's logs). Queried with ash obs query.

Operator A human or automated system that interacts with agentd via the ash CLI. Responsible for spawning agents, managing secrets, approving HITL requests, and monitoring the system.

Overlay filesystem A layered filesystem where each agent has a writable upper layer on top of a read-only base. Changes are isolated to the agent's workspace and can be snapshotted and rolled back.

Plan (lifecycle state) The state in which an agent reasons about its next action. The agent calls agent.plan() to produce an action plan before entering the Act state.

Pre-approval policy A rule that grants automatic approval for secret resolution without requiring per-use human confirmation. Policies can be declared in the manifest (spec.secret_policy) or added at runtime with ash secrets policy add.

Replay debugger A tool for post-hoc analysis of an agent's execution. Merges audit log, observation log, and workspace snapshot history into a unified timeline. Accessed via ash replay timeline.

Secret A sensitive credential value (API key, token, password) stored in agentd's in-memory Sealed Credential Store. Never written to disk. Referenced in tool arguments using {{secret:<name>}} handles.

Sealed Credential Store agentd's in-memory store for secrets. Values exist only in heap memory, are never serialized to disk, and are never included in IPC responses. Only [REDACTED:<name>] placeholders appear in logs.

Seccomp-BPF A Linux kernel feature (Secure Computing Mode with Berkeley Packet Filter) used to restrict the system calls available to agent processes. One of the five security layers in agentd's sandbox.

Supervisor An agent that spawned one or more child agents. A supervisor can read a child's observation log, receive escalations, and grant capabilities to the child.

Trust level A coarse-grained permission tier: untrusted < sandboxed < trusted < privileged. Declared in the manifest. Determines the ceiling for capabilities the agent may hold and the sandbox enforcement level.

Workspace The overlay filesystem directory allocated to each agent. Contains all files the agent creates or modifies during its execution. Can be snapshotted, diffed, rolled back, and archived.

{{secret:<name>}} The handle syntax for referencing a secret in tool call arguments. agentd resolves the handle to the plaintext value inside the tool dispatch layer; the agent's LLM context never sees the plaintext.