https://github.com/arais-labs/sentinel
Sentinel is your AI command center for getting things done.
https://github.com/arais-labs/sentinel
agents ai assistant automation chatbot claw cli llms machine-learning ui
Last synced: 20 days ago
JSON representation
Sentinel is your AI command center for getting things done.
- Host: GitHub
- URL: https://github.com/arais-labs/sentinel
- Owner: arais-labs
- License: agpl-3.0
- Created: 2026-02-25T10:58:32.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-29T03:57:34.000Z (23 days ago)
- Last Synced: 2026-05-29T05:25:33.119Z (23 days ago)
- Topics: agents, ai, assistant, automation, chatbot, claw, cli, llms, machine-learning, ui
- Language: Python
- Homepage:
- Size: 4.71 MB
- Stars: 22
- Watchers: 2
- Forks: 2
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Notice: NOTICE
Awesome Lists containing this project
README
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](https://arais.us).
📖 **Docs:** **[sentinel.arais.us](https://sentinel.arais.us)**
## Quick links
- [Quick Start](#quick-start)
- [Architecture](#architecture)
- [What Sentinel can do](#what-sentinel-can-do)
- [Documentation](#documentation)
- [Security model](#security-model)
- [Contributing](#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
```text
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
```bash
git clone https://github.com/arais-labs/sentinel.git
cd sentinel
```
### 2) Launch Sentinel CLI
```bash
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
```bash
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
```bash
docker compose -f docker-compose.dev.yml up --build
```
### Desktop app
The Electron desktop package is under [`apps/desktop/sentinel`](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](https://sentinel.arais.us)**
- Docs site source: [`docs-site/`](docs-site)
- Intro: [`docs-site/docs/introduction.md`](docs-site/docs/introduction.md)
- Quickstart: [`docs-site/docs/quickstart.md`](docs-site/docs/quickstart.md)
- Installation guide: [`docs-site/docs/guides/installation.md`](docs-site/docs/guides/installation.md)
- CLI reference: [`docs-site/docs/guides/cli-reference.md`](docs-site/docs/guides/cli-reference.md)
- API reference: [`docs-site/docs/reference/api.md`](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](CONTRIBUTING.md) and [SECURITY.md](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](docs-site/docs/guides/runtime-exec-security.md).
## License
GNU AGPL-3.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).