Architecture

Scarab-Runtime uses a userspace-first design. Security enforcement is handled entirely by Linux kernel primitives via a swappable PlatformEnforcer abstraction, with no kernel modules required.

Component Diagram

Scarab Runtime architecture overview

agentd: The Daemon

agentd is the trusted root of the system. It:

  • Spawns agent processes from manifest files, injecting SCARAB_AGENT_ID and SCARAB_SOCKET
  • Manages the lifecycle state machine (Init → Plan → Act → Observe → Terminate)
  • Runs the tool registry and dispatches all tool calls
  • Enforces capability checks on every IPC request
  • Maintains the audit trail, memory store, observation log, and workspace snapshots
  • Runs the message bus and blackboard
  • Manages secrets in heap-only sealed storage
  • Monitors for behavioral anomalies
  • Routes escalations up the agent hierarchy
  • Embeds the HTTP API gateway (agentd-api) on 127.0.0.1:8080

agentd is not an agent itself; it is the trusted root that applies security profiles to all agents.

ash: The Shell

ash is a CLI client that communicates with agentd over the same Unix socket agents use. It provides 25+ subcommand groups for every aspect of agent management.

libagent: The Library

libagent is the shared crate used by both agentd and agent binaries:

  • types.rs - AgentInfo, LifecycleState, TrustLevel, ResourceLimits, PlanStep
  • capability.rs - capability token parsing and glob matching
  • manifest.rs - YAML manifest parsing and validation
  • audit.rs - hash-chained audit entry types
  • ipc.rs - all Request/Response protocol variants
  • client.rs - AgentdClient typed async IPC client
  • agent.rs - Agent SDK high-level wrapper

IPC Protocol

All communication between agents/ash and agentd uses JSON over a Unix domain socket with a 4-byte big-endian length prefix:

IPC wire protocol

Default socket path: /run/agentd/agentd.sock
Override with SCARAB_SOCKET environment variable or --socket flag on ash.

Security Layers

Scarab-Runtime employs defense in depth with five independent enforcement layers:

  1. Tool dispatch: capability check before every tool invocation
  2. seccomp-BPF: per-agent syscall allowlist derived from manifest at spawn time
  3. AppArmor: per-agent MAC profile constraining file and network access
  4. cgroups v2: per-agent resource limits (memory, CPU shares, open files)
  5. nftables: per-agent network policy (none / local / allowlist / full)

Additionally, each agent runs in its own set of Linux namespaces (PID, network, mount) for process isolation.

Workspace Isolation

Every agent gets an overlayfs workspace. Writes go to an upper layer; the lower layer (base filesystem) is never modified. Snapshots checkpoint the upper layer. Rollback restores a previous snapshot. Commit promotes the upper layer permanently.