LBE – open-source execution control layer for AI agents

Notifications You must be signed in to change notification settings

Fork 0

Star 0

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

40 Commits

40 Commits

assets

assets

dist

dist

LICENSE

LICENSE

README.md

README.md

package.json

package.json

types.d.ts

types.d.ts

Repository files navigation

LBE puts a local policy gate between what an AI agent proposes and what the system actually executes. Every action — file write, shell command, anything — is validated locally before it runs. No cloud service. No daemon.

Used in production: LBE is the safety engine inside Letterblack for After Effects — every AI-generated script and automation command passes through it before touching a live project.

Which package do you need?

I want… Package

LBE to handle file writes and shell commands for me (full controller) @letterblack/lbe-exec

Just the allow/deny decision — I'll execute it myself @letterblack/lbe-sdk ← you are here

Install

npm install @letterblack/lbe-sdk

Requires Node.js ≥ 20.9.0.

Quick start

import { execute } from '@letterblack/lbe-sdk';

const request = { version: '1.0', request_id: 'req-001', timestamp: Math.floor(Date.now() / 1000), actor: { id: 'agent:local', role: 'agent' }, intent: { type: 'command', name: 'write_file', payload: { target: 'out.txt' } }, context: { workspace: process.cwd(), env: {}, history: [] }, constraints: { policy_mode: 'strict', timeout_ms: 5000 }, auth: { signature: '', nonce: '' } };

const result = JSON.parse(execute(JSON.stringify(request))); // Approved: { ok: true, decision: 'allow', ... } // Blocked: { ok: false, decision: 'deny', error: { stage, message } }

execute(input: string): string — accepts JSON, returns JSON. The runtime validates and returns a decision. The host acts on the decision.

Request fields

Field Required Description

version Yes "1.0"

request_id Yes Caller-supplied unique identifier

timestamp Yes Unix timestamp in seconds

actor Yes { id, role } — identity of the requesting agent

intent Yes { type, name, payload } — what the agent wants to do

context Yes Workspace path and caller context

constraints Yes policy_mode and timeout_ms

auth Yes Host-supplied signature and nonce

Observer mode — start here

Not ready to block? Start in observer mode. Every request is fully validated and logged exactly as it would be in enforcement — but nothing is blocked. Watch what the agent is doing before you decide what to deny.

npx lbe init # create lbe.policy.json in observer mode npx lbe enforce # switch to blocking npx lbe observe # switch back to advisory

CLI reference

Command Purpose

npx lbe init Create project-local policy and key state in observer mode

npx lbe policy-add Add a rule to the active policy

npx lbe observe Set advisory (log-only) mode

npx lbe enforce Set blocking mode

npx lbe run Validate and execute a proposal from --in

npx lbe verify Validate a proposal without executing

npx lbe dryrun Validate and simulate without executing

npx lbe health Check all required files are present and readable

npx lbe audit-verify Verify the audit log hash chain

How the gate pipeline works

Every request enters a 7-gate pipeline. A failure at any gate returns a structured denial — the remaining gates are not evaluated.

[1] Schema required fields and structural validity ↓ [2] Timestamp permitted clock-skew window (±10 minutes) ↓ [3] Key lifecycle trusted key, active, not expired ↓ [4] Signature Ed25519 request authenticity ↓ [5] Rate limit per-requester sliding-window limit ↓ [6] Nonce single-use replay protection ↓ [7] Policy configured authorization (deny-wins) ↓ allow / deny / error — structured result returned to host

The WASM runtime owns all gate decisions. Your host receives the decision and acts on it. Nothing executes inside the runtime.

When a request is approved

The agent produces a signed action proposal.

Identity is confirmed against a locally held key — no network call required.

The project policy is evaluated. The action is approved.

The host executes the write or command inside the allowed workspace.

The audit chain is extended — every approved action appends a hash-linked entry to the local log, permanently verifiable, impossible to silently remove.

A structured result returns: whether it succeeded, which rules matched, and the audit entry identifier.

The application stays in control. @letterblack/lbe-sdk decides whether the action was permitted and hands the answer back. It does not execute for you.

When a request is blocked

The agent attempts an action — whether by mistake, misconfiguration, or a deliberate bypass attempt.

The policy gate closes immediately. The WASM runtime stamps the request denied before any adapter is reached.

The shell is untouched. The filesystem is unchanged.

The denial is written to the immutable audit log — chain sealed, evidence preserved.

No partial execution. No silent failures. Denial is a first-class outcome, not an error.

What this covers

Threat Gate

Malformed or incomplete request Schema

Stale or replayed request Timestamp + Nonce

Tampered or expired key Key lifecycle + Signature

Excessive requests from one actor Rate limit

Action not permitted by project policy Policy — deny-wins

Agent writing outside project root Scope check in host after decision

What ships

dist/index.js WebAssembly runtime loader and execute() dist/cli.js Local CLI (npx lbe) dist/lbe_engine.wasm Verified runtime binary dist/wasm.lock.json Runtime integrity lock (SHA-256 of wasm binary) assets/lbe-gates.jpg Gate sequence diagram assets/story-allow.jpg Approved-request storyboard assets/story-deny.jpg Blocked-request storyboard assets/runtime-boundary.svg Runtime boundary diagram assets/lbe-gates.png Gate sequence diagram (full resolution) assets/story-allow.png Approved-request storyboard (full resolution) assets/story-deny.png Blocked-request storyboard (full resolution) types.d.ts TypeScript declarations

At load time the runtime verifies lbe_engine.wasm against wasm.lock.json. A missing, modified, or swapped binary fails before any request is processed.

Source code, controller implementation, adapters, tests, keys, and runtime state are not included.

Limits

This package validates requests routed through its runtime. It does not provide kernel-level process isolation, network-egress control, multi-tenant separation, or a hosted control plane.

For an in-process controller with file operations, shell, and policy management built in, see @letterblack/lbe-exec.

About

The execution-control layer between AI agent decisions and real-world actions.

github.com/Letterblack0306/LetterBlack-Sentinel

Topics

automation

mcp

rollback

npm-package

wasm

audit

developer-tools

audit-log

governance

ai-safety

policy-engine

ai-agents

local-first

agent-framework

llm

agent-safety

Resources

Readme

License

View license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks

Report repository

Releases 5

v1.2.20

Latest

Jun 21, 2026

+ 4 releases

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.