Sentinel

Sentinel is a runtime safety gateway for AI coding agents.

It wraps local execution from tools like Codex, Claude Code, Gemini, and shell workflows, evaluates risky actions before they run, records audit logs, and can add OS-level protection for sensitive local paths.

Sentinel governs the local execution layer. It does not inspect, block, proxy, or decrypt Codex/Claude/Gemini remote reasoning or model/API traffic.

What It Does

• Checks shell, Git, file, database, and deploy commands against deterministic policy rules
• Blocks, warns, or asks for approval before risky local commands run
• Wraps AI CLI sessions with PATH proxy interception
• Blocks protected path reads such as .env and secrets/**
• Optionally uses macOS sandbox-exec to block direct protected path reads like /bin/cat .env
• Captures session stdout/stderr transcripts with secret redaction
• Writes JSONL audit logs with session IDs and policy hashes
• Keeps interactive agent sessions attachable through managed tmux sessions

Runtime

The npm package is Sentinel CLI. It uses the native-free TypeScript runtime and does not include Rust binaries, prebuilt native artifacts, native effect monitoring, hosted dashboards, organization policy control, SSO, SCIM, central approvals, compliance reporting, or a runtime daemon.

Install

Install the npm TypeScript runtime:

npm install -g @rustyelement/cli
sentinel --help
sentinel capabilities

Quick Start

Initialize policy in a repository:

sentinel init
sentinel policy validate

Check risky commands without executing:

sentinel check "git push origin main"
sentinel check "terraform apply"
sentinel check "cat .env"

Run a command through Sentinel:

sentinel run -- echo safe
sentinel run -- git push origin main

Run an AI CLI through Sentinel:

sentinel codex --transcript --os-sandbox
sentinel claude --transcript --os-sandbox
sentinel gemini --transcript --os-sandbox

Install secure wrappers:

sentinel install-shims --secure --dir ~/.local/bin --force
export PATH="$HOME/.local/bin:$PATH"

This creates:

• codex-safe
• claude-safe
• gemini-safe

Secure shims run AI CLIs through:

sentinel session --os-sandbox --transcript -- <tool>

Commands

sentinel init [--force] [--path <path>]
sentinel check "<command>"
sentinel run -- <command> [args...]
sentinel session [--transcript] [--os-sandbox] [--tmux] [--tmux-name <name>] [--tmux-detached] -- <command> [args...]
sentinel codex [--transcript] [--os-sandbox] [--tmux] [--tmux-name <name>] [--tmux-detached] -- [codex args...]
sentinel claude [--transcript] [--os-sandbox] [--tmux] [--tmux-name <name>] [--tmux-detached] -- [claude args...]
sentinel gemini [--transcript] [--os-sandbox] [--tmux] [--tmux-name <name>] [--tmux-detached] -- [gemini args...]
sentinel shell [--transcript]
sentinel install-shims [--secure] [--dir <dir>] [--force]
sentinel doctor [--shim-dir <dir>]
sentinel tmux doctor [--registry <tmux-sessions.jsonl>] [--json]
sentinel tmux list [--registry <tmux-sessions.jsonl>] [--json]
sentinel tmux attach <session-id-or-tmux-name> [--registry <tmux-sessions.jsonl>]
sentinel tmux detach <session-id-or-tmux-name> [--registry <tmux-sessions.jsonl>]
sentinel tmux kill <session-id-or-tmux-name> [--registry <tmux-sessions.jsonl>]
sentinel tmux status <session-id-or-tmux-name> [--registry <tmux-sessions.jsonl>] [--json]
sentinel tmux reconcile [--registry <tmux-sessions.jsonl>] [--json]
sentinel logs [--session <id>] [--sessions] [--json]
sentinel explain <log-id>
sentinel export [--session <id>] [--output <path>] [--envelope] [--org-id <id>] [--workspace-id <id>] [--agent-id <id>] [--user-id <id>] [--team-id <id>] [--signing-key-env <ENV>]
sentinel policy validate
sentinel policy show [--json]
sentinel policy rules [--action <action>] [--severity <severity>] [--id <rule-id>] [--json]
sentinel capabilities [--json]

Tmux Remote Operations

Sentinel can launch interactive agent wrappers inside managed tmux sessions when --tmux is set:

sentinel codex --tmux --transcript --os-sandbox
sentinel claude --tmux --transcript --os-sandbox
sentinel gemini --tmux --transcript --os-sandbox

Without --tmux, agent wrappers run directly inside a Sentinel session proxy. With --tmux, Sentinel attaches to the new tmux session immediately. Use --tmux-detached to create the managed tmux session and return without attaching.

Discover and attach from the same host, SSH, Tailscale SSH, VPN, or a mobile shell:

sentinel tmux list
sentinel tmux attach <session-id-or-tmux-name>

Detach from tmux with:

Ctrl-b d

Remote attach inherits OS account permissions. Sentinel does not expose a public terminal server; keep remote access behind your existing SSH/VPN/Tailscale controls.

Policy

Default lookup order:

1. ./sentinel.policy.yaml
2. ./.sentinel/policy.yaml
3. ~/.config/sentinel/policy.yaml
4. embedded default policy

Example:

protected_paths:
  - .env
  - .env.*
  - secrets/**
  - infra/**

rules:
  - id: block-main-push
    description: Block direct pushes to protected branches.
    match:
      command_regex: "git push .* (main|master)"
    action: block
    severity: critical
    reason: "Direct push to protected branch is blocked."

Actions:

• allow
• warn
• require_approval
• block

Audit And Transcripts

Sentinel writes JSONL audit entries. Each entry includes:

• command, cwd, git branch, git remote
• action, severity, matched rules, reason
• exit code and approval text when relevant
• session_id
• policy_source
• policy_hash

Inspect logs:

sentinel logs
sentinel logs --sessions
sentinel logs --session <session-id>
sentinel logs --json
sentinel explain <log-id>

Export logs:

sentinel export
sentinel export --session <session-id>
sentinel export --output sentinel-export.json

With --transcript, stdout/stderr are copied to:

<log-dir>/sessions/<session-id>/stdout.log
<log-dir>/sessions/<session-id>/stderr.log

For sentinel shell --transcript, entered commands are also written to:

<log-dir>/sessions/<session-id>/input.log

Transcript files redact common secret patterns such as OpenAI keys, Anthropic keys, GitHub tokens, AWS access keys, JWTs, password/token assignments, and DB URLs.

OS Sandbox

On macOS, --os-sandbox uses /usr/bin/sandbox-exec to deny reads from policy protected_paths.

This helps with bypasses such as:

/bin/cat .env

The sandbox is opt-in:

sentinel session --os-sandbox -- codex
sentinel codex --os-sandbox

Secure shims enable it by default.

Network Boundary

Sentinel does not deny network access.

Codex/Claude/Gemini remote reasoning and model/API traffic are outside Sentinel's responsibility boundary. Sentinel controls and records local execution behavior: commands, files, Git, DB/deploy tools, transcripts, and audit logs.

Network observability starts with metadata and local process context. Sentinel does not intercept, decrypt, or inspect network payloads.

Verify Setup

sentinel doctor
sentinel doctor --shim-dir ~/.local/bin

doctor checks:

• policy loading
• log directory
• macOS sandbox availability
• shim installation
• secure shim mode
• PATH setup

License

Sentinel is licensed under the Apache License, Version 2.0. See LICENSE.

Current Limits

• Policy matching is deterministic and regex/path based.
• --os-sandbox is macOS-specific and depends on sandbox-exec availability.
• Protected path enforcement is currently read-focused.
• Sentinel does not inspect remote model reasoning or encrypted API payloads.