sheltron 0.1.0

Sidecar safety and security kernel for local agent systems

Sheltron

1. Introduction

Sheltron is a sidecar safety layer for local AI agents. This repo contains the Sheltron core, runtime guards, CLI, MCP integration, and adapters for agent systems like OpenClaw.

It protects the action boundary, not just the prompt: before an agent touches files, runs shell commands, calls the network, sends messages, or writes memory, Sheltron can allow, deny, or ask for approval. The goal is simple: keep agents useful on your machine without giving every tool call a blank check.

2. Supported Functions

nanobot: nanobot-ai==0.1.4.post6, nanobot-ai==0.1.5.post2

• Filesystem: workspace/protected-path guards for reads, writes, edits, and listings.
• Shell: approval-gated exec with audit records.
• Network/search: guarded fetch/search; external content marked untrusted.
• Messaging/scheduling: approval and redaction for sends, cron, and spawned tasks.
• Memory: history and long-term memory writes routed through candidate review.

OpenClaw: OpenClaw 2026.4.21

• Filesystem: guards mapped read/write/edit/patch tools, including memory/bootstrap/config paths.
• Shell/process: approval-gated host execution.
• Network/search: guarded fetch/search with prompt-injection hardening.
• Messaging: recipient/content policy with redaction-aware approval.
• Bootstrap/prompt: filters unsafe bootstrap, skill, and config injection.
• Memory: durable writes reviewed as memory candidates.

Planned To-do

• Hermes: no adapter or safety coverage is shipped yet.
• Broader LLM-targeting defence: planned detectors for prompt injection, fake approval claims, memory poisoning, deny-workaround loops, and suspicious outbound/shell intent.
• Deeper host coverage: broader interception of host-specific tools as nanobot, OpenClaw, and future agent APIs evolve.
• Verify pip installation

3. Installation Guide

Sheltron requires Python 3.11+. uv is the primary supported installation and development path.

Clone and Install Sheltron

From a source checkout, use an editable uv tool install. This gives you a global sheltron command while keeping Python source edits live from the checkout.

git clone https://github.com/sheltron-ai/sheltron.git
cd sheltron
uv sync --python 3.11 --extra dev
uv tool install --editable .

Link Sheltron to the agent you have installed

nanobot:

sheltron link nanobot

OpenClaw:

sheltron link openclaw

Start protected run

sheltron <agent> ...

nanobot:

sheltron nanobot agent

OpenClaw:

sheltron openclaw gateway run

Or, use always-on mode

Turn on always-on:

sheltron on nanobot

sheltron on openclaw

And run

nanobot agent / openclaw gateway run / ...

commands with sheltron always-on.

Turn off always-on:

sheltron off <agent>

Unlink agent (only needed for uninstall or reinstall)

sheltron unlink <agent>

Uninstall

Before removing Sheltron itself, unlink agent integrations first:

sheltron unlink --all
uv tool uninstall sheltron

4. Example Use Cases

These examples show one protected action for each supported adapter.

Example: nanobot Filesystem Protection

Link nanobot:

sheltron link nanobot

Start a protected nanobot session in a disposable workspace:

mkdir -p examples/nanobot/live_test
sheltron nanobot agent --workspace "$PWD/examples/nanobot/live_test"

Inside nanobot, check Sheltron status:

Check Sheltron status.

Expected behavior:

• nanobot should use sheltron_status
• the status should report that Sheltron is active for this session

Inside nanobot, test filesystem protection:

Write ../outside.txt with the exact text "approval test".

Expected behavior:

• writing outside the workspace should require approval
• the file must not be written before approval
• the model should explain the Sheltron policy result instead of trying another unsafe path

Example: OpenClaw Exec Protection

Link OpenClaw:

sheltron link openclaw

For a protected gateway-backed session, start the gateway through Sheltron:

sheltron openclaw gateway run

In OpenClaw, check Sheltron status:

Is Sheltron on?

Expected behavior:

• OpenClaw should use sheltron_status
• the status should report protected-run or global protection

In OpenClaw, test shell execution:

Run the exact shell command bash -lc "printf openclaw-exec-test" and return only stdout.

Expected behavior:

• OpenClaw's tool hook should route the exec request through Sheltron
• shell execution should require approval before running
• if approval is unavailable, the tool call should fail closed rather than execute silently

5. License

Sheltron is licensed under the Apache License 2.0.

Copyright 2026 Sihao Ding. See NOTICE.