Sentinel

One autonomous agent. Full execution stack.

Sentinel is a self hosted AI operator that turns intent into execution. It combines an agent runtime, browser automation, scheduling, memory, approvals, and tool access in one product.

One deployment hosts multiple isolated instances — each with its own database, agent runtime, and LLM provider — managed from a single control plane (the CLI or the desktop app).

Built by ARAIS.

📖 Docs: sentinel.arais.us

Quick links

• Quick Start
• Architecture
• What Sentinel can do
• Documentation
• Security model
• Contributing

What Sentinel can do

• Run multi step tasks with tool calls and recovery.
• Use a real browser with Playwright and live VNC monitoring.
• Execute scheduled runs with cron or heartbeat triggers.
• Keep persistent hierarchical memory across sessions.
• Delegate bounded work to sub agents.
• Gate risky actions behind human approvals.
• Connect to custom modules for data and actions.
• Run git operations freely and only gate at push or PR creation, so the agent moves fast without surprise commits to main.
• Authenticate with your existing Claude Code or Codex CLI OAuth token, no extra API subscription needed.

Architecture

User / Telegram / Trigger
        ↓
  Sentinel UI
        ↓
  Agent Runtime (Python)
  ├── Context builder (memory + history)
  ├── LLM provider (Anthropic / OpenAI / failover)
  ├── Tool adapter (modules + browser + runtime + git)
  ├── Approval gate (pause/resume on sensitive actions)
  └── Estop service (freeze or kill execution at any depth)
        ↓
  Module Control Plane
  ├── Custom tool modules (sandboxed Python)
  ├── Data modules (persistent record stores)
  ├── Permissions (allow / approval / deny per action)
  └── Approval queue (async human review)
        ↓
  Browser + External APIs + Git

Quick Start

1) Clone

git clone https://github.com/arais-labs/sentinel.git
cd sentinel

2) Launch Sentinel CLI

bash ./sentinel-cli.sh

For first run:

1. Let the CLI create or reconcile the root .env. Prod mode proposes generated values and rejects placeholders/default credentials. Dev mode is explicit via ./sentinel-cli.sh --dev and may write local dev defaults.
2. Choose Start Stack
3. Choose Instances -> Create Instance
4. Create the default logical instance, for example main

3) Open Sentinel

Default URLs:

• http://localhost:4747/ Sentinel
• http://localhost:4747/modules modules
• http://localhost:4747/vnc/ live browser monitor

4) Sign in

Use the admin username and password from the root .env.

Compose / server mode: admin credentials live in .env (SENTINEL_AUTH_USERNAME / SENTINEL_AUTH_PASSWORD) and are re-applied to the manager database on every backend startup. Rotate by editing .env and restarting the backend; the POST /auth/change-password endpoint is disabled.

Desktop mode (APP_ENV=desktop): the manager database is the source of truth. .env values, if present, are only used to seed credentials on the very first launch. Use the in-app password-change flow to rotate.

Installation paths

Recommended

• Use sentinel-cli.sh for instance lifecycle, auth seeding, startup, status, logs, and cleanup.
• The CLI defaults to production mode and uses docker-compose.yml.
• Create a root .env from .env.example for the default production-shaped path.
• Use ./sentinel-cli.sh --dev for explicit local development mode. The CLI can write a complete root .env with dev-safe defaults.

Manual compose

cp .env.example .env
# edit .env and replace the placeholder secrets
docker compose up --build -d

docker-compose.yml is the production-shaped compose file and fails clearly unless these secrets are provided. For local development defaults, use docker-compose.dev.yml.

Dev mode

docker compose -f docker-compose.dev.yml up --build

Desktop app

The Electron desktop package is under apps/desktop/sentinel. It is a native management shell for local Sentinel instances. The CLI remains supported for terminal workflows.

Repository layout

• apps/backend/sentinel Sentinel backend
• apps/desktop/sentinel Sentinel Electron desktop shell
• apps/frontend/sentinel Sentinel frontend
• infra/ gateway and runtime wiring
• docs-site/ full documentation source
• docs/ project notes and assets

Documentation

• Live docs site: sentinel.arais.us
• Docs site source: docs-site/
• Intro: docs-site/docs/introduction.md
• Quickstart: docs-site/docs/quickstart.md
• Installation guide: docs-site/docs/guides/installation.md
• CLI reference: docs-site/docs/guides/cli-reference.md
• API reference: docs-site/docs/reference/api.md

Security model

Sentinel uses explicit policy based controls for module actions:

• allow executes immediately
• approval pauses and requests human review
• deny blocks action

High risk actions can be reviewed before execution. Emergency stop levels can freeze active execution when needed.

Contributing

See CONTRIBUTING.md and SECURITY.md.

Runtime Exec Security Model

The agent runs shell commands through the runtime system module, which executes on each instance's managed SSH/tmux runtime target inside an OS-level sandbox — Bubblewrap on Linux runtimes and macOS Seatbelt (sandbox-exec) on macOS. All commands run confined; there is no unconfined or "root" execution mode.

The module exposes four actions: runtime.user (run a command in the session workspace) plus runtime.terminal_list, runtime.terminal_read, and runtime.terminal_close for managing tmux-backed terminals. Use background=true for long-running commands. See Runtime Exec Security.

License

GNU AGPL-3.0. See LICENSE and NOTICE.