Agents propose.
Policy decides.

A deterministic control plane for AI-agent actions. Verify signed permits, bind authority to exact tool arguments, and preserve auditable evidence — before a trusted handler acts.

Explore the decision flow View source

Local-firstMIT licensedPython 3.9+

shards / governance.inspect● ONLINE

01 / Intent under review

agent_idresearch-agent-01

requested_tooltool.execute

effective_args{ action: "read" }

GATE 01

Verify permit

GATE 02

Match policy

✓

Authorized requestPermit & inputs validated

ALLOW

→ signature verified

→ parameters exact match

→ decision recorded

illustrative / not a live API requestDECISION COMPLETE

3.9 – 3.15Python versions in CI

Ed25519Optional signed permit path

Fail closedExplicit authorization boundaries

MITOpen-source licence

The control boundary

Give tool execution a decision point.

The model provides a request, not its own authority. Shards-Kernel sits in the trusted execution path to verify what was permitted and capture what happened.

STEP / 01

Agent intent

An untrusted model proposes a tool operation.

STEP / 02

Signed permit

Verify identity, scope, and effective arguments.

STEP / 03

Policy decision

Explicit allow or deny. No implied authority.

STEP / 04

Trusted handler

Execute admitted actions and capture evidence.

The kernel governs trusted Python handlers; it does not isolate arbitrary code as an operating-system sandbox.

Core primitives

Control, verify, account.

Small, composable controls for consequential agent actions. Built around determinism rather than asking a language model to police itself.

Exact-argument authority

Bind authorization to the effective values a handler receives, including defaults and nested parameters.

Signed permits

Cryptographic permit verification through the optional Ed25519-backed crypto path.

Replay protection

Apply nonce and permit-consumption controls to resist repeated or stale authorization.

Audit evidence

Record decisions and outcomes in tamper-evident audit structures that can be inspected later.

Bounded admission

Guard concurrent tool admission and distinguish queued control requests from confirmed outcomes.

Developer integration

Use the Python API, command-line interface, and optional MCP integration as a control layer around trusted tools.

Explore the decisions

See the boundary in action.

Switch between sample requests to see how an authorization gate responds when permit conditions change.

Interactive illustration. These fixed examples simulate outcomes for explanation only; they do not contact a running Shards-Kernel instance or execute tools.

decision-lab / example inputREAD ONLY ●

Request + permit

{
  "tool": "files.read",
  "args": {
    "path": "/report.txt"
  },
  "permit": {
    "scope": "files.read",
    "expires": "valid",
    "signature": "valid"
  }
}

Decision trace

ALLOW / admitted

✓Signature verified
✓Scope and effective inputs match
✓Permit is within validity window
✓Admission and audit decision recorded

Example states only. An actual deployment must define trusted handlers and enforce these checks in its execution path.

Get started in your environment

Install locally. Inspect everything.

Start with the published PyPI package. Run an offline demonstration to inspect the control flow without connecting a real agent or external service.

✓One Python package, with opt-in integrations

✓Built-in CLI demonstration

✓Source, issues, and release notes are public

terminal / quickstart

# Install the v0.1.3 release with crypto support
$ python -m pip install "shards-kernel[crypto]==0.1.3"

# Inspect strict configuration
$ shards-kernel info --variant strict

# Run an offline, JSON-formatted demonstration
$ shards-kernel demo --json

The offline demo uses a built-in example handler. It does not connect to live tools.

Clear operating boundaries

Security starts with precision.

Shards-Kernel is an authorization and audit component, not a claim that every surrounding system is automatically secured.

Designed for explicit governance

Local control-plane integration, permit enforcement, replay resistance, decision accounting and evidence around trusted handler calls.

Not a substitute for runtime isolation

It is not an operating-system sandbox, a hosted remote MCP gateway, or a guarantee of exactly-once external effects. Process isolation, network controls and operational safeguards remain your responsibility.

Build with explicit authority

Trust the execution boundary.
Not the prompt.

Review the implementation, run the demo, and integrate deterministic authorization where your agents reach real tools.

Explore the repository Read release notes

Agents propose.Policy decides.