Security Architecture

Safety &
Sandboxing

Weaver assumes that AI agents are fundamentally untrusted actors. Two independent safety layers protect the codebase: the Double-Lock validation harness (syntactic + semantic checks on edits to supported files, with exemptions detailed below) and the Birdcage sandbox (kernel-level process isolation for all external tools). They operate independently — the Double-Lock guards code correctness; the sandbox guards system integrity.

The Double-Lock

Every act command passes through a two-phase verification harness before any file is written to disk. For files with a recognised parser and language-server path, edits are applied to in-memory copies, checked syntactically, then checked semantically. Unsupported file types are preserved in the transaction, but they do not receive the full parser-plus-diagnostics lock sequence.

LOCK 1 · SYNTACTIC

Syntactic Lock

Each modified file with a supported parser is checked with Tree-sitter to confirm a valid syntax tree. Structural errors — unbalanced braces, missing semicolons, malformed declarations — are caught here. Files that fail parsing are rejected immediately; the filesystem stays untouched.

  • Tree-sitter parsers for Rust, Python, TypeScript
  • Fast, local — no language server needed
  • Unknown file types pass through without parser or semantic checks
LOCK 2 · SEMANTIC

Semantic Lock

If the syntactic lock passes, modified content is submitted to the configured language server. The daemon requests fresh diagnostics and compares them against the pre-edit baseline. Any new errors or high-severity warnings cause the semantic lock to fail.

  • LSP diagnostics via didOpen / didChange / didClose
  • Compares against pre-edit baseline
  • No disk writes until both locks pass

When a lock fails

The harness returns a structured error identifying the lock phase (syntactic or semantic), the affected files, optional line/column locations, and human-readable messages. Agents can use this to diagnose problems and regenerate corrected edits. The filesystem is never left in a partially written state.

Birdcage Boundaries

Filesystem Jail

mount_policy

The agent sees a virtualized filesystem. It can only write to the specific project directory explicitly mounted for the task.

/project (RW) /usr/lib (RO) /etc (Hidden)

Network Gap

egress_policy

By default, the network namespace is empty (loopback only). Access to package registries and APIs must be explicitly allowlisted via proxy.

ALLOW api.uxpilot.ai:443 ALLOW crates.io:443 DENY *

Resource Quotas

quota_guard

cgroups limit CPU cycles, memory usage, and process counts to prevent fork bombs, runaway builds, or mining attempts by rogue agents.

CPU: 2 cores MEM: 4GB PIDS: 50 max

Threat Model

We assume the LLM provider may be compromised, hallucinating, or malicious. Weaver is designed to operate safely even if the agent is actively trying to escape.

01

Exfiltration Prevention

Strict egress filtering prevents agents from sending your codebase to unauthorized external servers.

02

Destructive Action Mitigation

Read-only system mounts prevent `rm -rf /` or modification of critical binaries.

03

Supply Chain Injection

Dependency lockfiles are verified against policies to prevent adding malicious crates or packages.

Operational Guidance

Do

  • Run verify often
  • Audit policy files
  • Use specific mounts
  • Review diffs manually

Don't

  • Run as root
  • Disable sandbox in prod
  • Share API keys in env
  • Blindly auto-merge

"Trust, but verify inside a chroot."

Configuration & Protocol Reference

Canonical reference

Keep the safety model here. Keep configuration defaults, daemon lifecycle, and the JSONL envelope in the docs hub. That page is now the maintained source of truth for operator-facing config and protocol details.

Configuration JSONL protocol Daemon lifecycle

Defaults

Built-in logging defaults remain info for log_filter and json for log_format. Use log_format = "compact" only when overriding that default.

Config keys

The safety model depends on the same top-level config keys documented in the docs hub: daemon_socket, log_filter, log_format, and repeatable [[capability_overrides]].

Wire format

Sandbox-protected tools still report through the daemon's normal JSONL envelope: stream frames during execution, then a final exit frame.

Understand the Agent's Mind

Explore how Sempai queries the codebase structure.

Next: Sempai Engine