@letterblack/lbe-core

Note: This repository is the public release mirror. Release/build authority lives in LetterBlack-LBE-Core.

LBE Core is local execution control for AI agents.

It evaluates file and shell actions routed through its execution boundary, records local evidence, and returns an allow/deny/proof outcome before agent work is treated as complete.

LBE is not an AI model, IDE, full OS sandbox, cloud monitor, or hosted control plane. It only controls actions that are routed through LBE.

Agent wants to act
        ↓
LBE validates workspace, policy, target, and evidence
        ↓
allow / deny / weak proof / error
        ↓
Host executes only if LBE approved
        ↓
Audit and proof records are written locally

Recommended install

Use the current clean release:

npm install @letterblack/[email protected]
npx lbe init
npx lbe assert-consumer
npx lbe proof --public

assert-consumer confirms this project is using LBE as an installed package dependency.

It does not certify LBE release safety.

Install and start

npm install @letterblack/[email protected]
npx lbe init
npx lbe status
npx lbe logs
npx lbe proof --public
npx lbe open-state

Requires Node.js >= 20.9.0.

Command summary:

| Command | Purpose | |---|---| | npx lbe init | Initialize LBE state for the current workspace | | npx lbe status | Show workspace policy, state, and proof status | | npx lbe logs | Show recent local LBE audit events | | npx lbe open-state | Open the central local state folder for this workspace | | npx lbe proof | Show the latest private proof result | | npx lbe proof --json | Print the latest proof as JSON | | npx lbe proof --public | Print a redacted proof safe for public sharing | | npx lbe status --all | List known local workspaces from the workspace registry |

What LBE does

LBE gives agent builders a local execution boundary:

• validates requested file and shell actions before execution
• keeps governed actions inside the intended workspace
• records local audit evidence
• tracks intent, target, file-index snapshots, and proof results
• supports private proof and public/redacted proof output
• preserves legacy .lbe/events.jsonl logs while using central local state

Most systems ask only:

Did the user approve this?

LBE asks a stricter question:

Is this exact action allowed to reach the filesystem or terminal, and can we prove what happened?

Local state and proof

LBE keeps state locally in a central per-user state folder. Each workspace has a stable workspace ID and its own event log.

In v1.3, an existing .lbe/events.jsonl remains local fallback truth and is imported into central state once. The source file is preserved.

Proof combines:

intent
  ↓
target
  ↓
file-index before action
  ↓
LBE audit event
  ↓
file-index after action
  ↓
proof/latest.json

Proof results:

| Result | Meaning | |---|---| | PASS | Evidence is complete and actual changes match declared intent | | FAIL | Evidence violates intent, policy, or expected file changes | | WEAK_PROOF | Target evidence was uncertain or required user confirmation |

Use:

npx lbe proof --public

for a redacted proof summary. Public proof redacts private paths, raw internal IDs, full diffs, hashes, and sensitive failure details.

What ships

The npm package ships the packaged runtime boundary, not the private source tree.

bin/lbe.js                    CLI shim
dist/cli/lbe.js               Bundled CLI runtime
dist/hooks/register.cjs       Hook preload runtime
dist/state/index.cjs          Packaged CJS state resolver
dist/state/appendCentral.cjs  Packaged central JSONL append helper
README.md
Release-README.md
CHANGELOG.md
LICENSE
package.json

The npm package must not include private implementation folders such as src/core/**, tests, local .lbe/** state, AppData state, diagnostic helpers, private keys, or workspace-local proof artifacts.

Limits

LBE controls only actions routed through its execution boundary.

It does not provide:

• kernel-level process isolation
• network-egress control
• multi-tenant separation
• hosted monitoring
• universal control over tools outside LBE's execution boundary

Central writes are best-effort. Local logs remain local.

Release status

Current aligned release:

@letterblack/[email protected]

Earlier 1.3.0, 1.3.1, 1.3.2, and 1.3.3 builds are superseded by 1.3.5.

One-sentence summary

LBE Core does not make the agent smarter. It makes the agent's execution path controlled, evidence-backed, and locally auditable.