Sentinel Labs

Sentinel Labs is a local-first sandbox and runtime wrapper for AI-agent security experiments. Version 0.1.4 packages the Sentinel CLI, framework launcher, sandbox backend abstraction, SQLite event store, evidence-backed diagnosis engine, local API/SSE service, and localhost security dashboard together.

Runtime data stays on your machine. The deployed Attack Log dashboard is only the visual template; Sentinel's local session store is the source of truth.

Installation

python -m pip install sentinel-lab==0.1.4
sentinel help

The PyPI project is sentinel-lab; the primary CLI command is sentinel.

Configure frameworks

sentinel agents

sentinel agents opens a Critiqor-style selector with OpenClaw, CC, Codex, and Custom. Built-in frameworks use their launch command internally, so users only need to run the Sentinel monitor command. Custom frameworks persist their name, executable, arguments, and launch command in ~/.sentinel-lab/config.json.

Non-interactive examples:

sentinel agents --framework openclaw
sentinel agents --framework cc
sentinel agents --framework codex
sentinel agents --framework custom --name "My Agent" --command "my-agent tui"
sentinel agents --list

After setup, Sentinel prints the recommended command, such as:

sentinel monitor openclaw

Run an experiment

sentinel monitor openclaw --attack prompt_injection --defense tool_permission_boundary

Other built-ins:

sentinel monitor cc
sentinel monitor codex

Sentinel creates a unique session, prepares the selected sandbox backend, starts the configured agent runtime inside that backend, preserves the interactive TUI where the backend allows it, injects SENTINEL_LAB_API_URL, SENTINEL_LAB_SESSION_ID, SENTINEL_LAB_FRAMEWORK, and SENTINEL_LAB_SANDBOX_DIR, then records sandbox, process, policy, and structured framework telemetry.

Sandbox backends are explicit about their guarantees. On macOS, Sentinel uses sandbox-exec when available to deny host filesystem access and outbound network by default while allowing the session workspace and required system executable paths. On platforms without an enforcing backend, Sentinel uses a reduced process-group backend and records that filesystem/network containment is unavailable.

The reduced backend is useful for lifecycle control and telemetry, but it is not a security sandbox. Sentinel does not market process groups as container or VM isolation.

To end an active experiment from another terminal:

sentinel finalize

sentinel finalize stops the wrapper and monitored runtime, generates the session diagnosis/evidence/workflow artifacts, and opens the local dashboard for that exact session:

http://127.0.0.1:43117/investigations/<SESSION_ID>

Open the latest completed investigation later:

sentinel dashboard

Observability boundary

Sentinel records generic process-level information for every configured framework: session ID, framework, PID, timestamps, duration, lifecycle, and shutdown/finalization events.

For deeper security telemetry, the agent runtime or a framework-specific adapter should emit structured Sentinel events. That is how Sentinel can capture model events, tool calls, tool results, external content, defenses, suspicious activity, parent/child relationships, and workflow evidence. A generic terminal wrapper cannot infer hidden framework internals that the framework never exposes.

Instrument Python

Framework adapters and agents can send structured runtime evidence with the injected environment variables:

from sentinel_lab import SentinelLabs, SentinelLabsClient

observed_agent = SentinelLabs.wrap(existing_agent)
result = observed_agent.run("Summarize the supplied page")

log = SentinelLabsClient()
log.external_content({
    "origin": "https://research.local/notes",
    "content_excerpt": "Untrusted page content",
})

with log.tool_call("browser.open", payload={"arguments": {"url": "https://example.test"}}):
    result = browser.open("https://example.test")

Plain process wrapping still works without instrumentation, but tool/model-level claims require structured events.

Trust boundary

UNTRUSTED
Agent, model output, agent subprocesses, downloaded/tool-generated content

TRUST BOUNDARY

TRUSTED
Sentinel orchestrator, sandbox policy, host collector, event store, analyzer, dashboard

Agent telemetry is untrusted input until the host collector normalizes it, assigns Sentinel event IDs, persists it, and links it to a session.

Local dashboard

The bundled dashboard is served by Sentinel on localhost and reads only real Sentinel data:

Agent Runtime
  -> Sandbox backend
  -> Sentinel Wrapper / telemetry bridge
  -> Event Stream
  -> SQLite / Session Store
  -> Diagnosis + Evidence + Workflow
  -> Local API / SSE
  -> Local Dashboard

Routes include /, /live, /investigations/<SESSION_ID>, /workflow, and /settings. Empty installs show empty states, not mock sessions.

Run artifacts

Each run is isolated under ~/.sentinel-lab/sessions/<session-id>/:

session.json     session metadata and complete event snapshot
events.jsonl     append-only raw event stream
diagnosis.json   claims, evidence references, and attack trace
evidence.json    claim-supporting event records
workflow.json    reconstructed nodes and edges

SQLite remains the query store at ~/.sentinel-lab/sentinel-lab.sqlite3.

Useful commands:

sentinel status
sentinel sessions
sentinel inspect SESSION-0001
sentinel inspect SESSION-0001 --json
sentinel --version

Configuration

export SENTINEL_LAB_HOME="$PWD/.sentinel-lab-data"
export SENTINEL_LAB_HOST=127.0.0.1
export SENTINEL_LAB_PORT=43117
export SENTINEL_LAB_SANDBOX_BACKEND=process-group-observation

Legacy ATTACK_LOG_* variables remain supported for adapter compatibility.

SENTINEL_LAB_SANDBOX_BACKEND can be set to darwin-sandbox-exec or process-group-observation. If the requested enforcing backend cannot actually apply on the host, Sentinel records the reduced fallback rather than claiming secure containment.

Publish 0.1.4

From the repository root:

./scripts/publish-pypi.sh

Enter a PyPI API token when prompted. The script cleans old release artifacts, builds, validates, verifies sentinel --version is 0.1.4, and uploads sentinel-lab==0.1.4. See PUBLISHING.md for details.

Development

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
PYTHONPATH=src python -m unittest discover -s tests -v
python -m build

See ARCHITECTURE.md for the system design.