# Talos

> Self-hosted, open-source AI agent for terminal and Telegram with a deterministic permission kernel that gates every tool call before execution.

Talos is a self-hosted, open-source AI agent written in Python that runs on your own machine, takes instructions over a chat channel (terminal, Telegram, email, or WhatsApp), reasons through a language model, and executes tools — but only after a deterministic security kernel has ruled on each action. The project is available under the MIT license on GitHub and is currently at v0.19.19-alpha.

## What It Is

Talos sits in the category of autonomous agent frameworks with a security-first design philosophy. Its core premise is that the language model proposes actions but never decides them: every tool call passes through `PolicyKernel.decide()`, which returns exactly three verdicts — `ALLOW`, `NEEDS_HUMAN`, or `DENY` — before any runner is invoked. Authority is represented as a capability token bound to exact arguments, valid once, for 30 seconds. A tool without a registered target extractor is `DENY` by construction, not by a rule someone wrote.

## How the Permission Kernel Works

The kernel's decision pipeline covers four broad classes of action:

- **Ordinary work** (reads, builds, tests, writes inside the workspace) — runs automatically
- **Risky but recoverable** (curl piped to shell, `git reset --hard`, `rm -rf <path>`) — asks the operator
- **Persistence and secrets** (`.bashrc`, systemd units, `~/.ssh`, the agent's own source) — asks the operator
- **Catastrophic** (`rm -rf /`, `mkfs`, `dd` to a block device, fork bomb) — refused unconditionally

`DENY` is evaluated before the approval check, so a human "yes" cannot reach a hardline rule. Approvals are one-shot, carry a five-minute TTL, and are re-verified against file hashes immediately before execution to prevent time-of-check/time-of-use races. The gate path (`policy.py`) is 919 lines and is designed to be readable in a single sitting.

## The Autonomy Dial and Unattended Ceiling

`/autonomy 0..5` sits above the kernel and can only tighten, never loosen. Level 5 is the unfiltered kernel; level 0 refuses everything. During unattended runs (timed schedules, background tasks, delegated sub-runs), `NEEDS_HUMAN` automatically becomes `DENY` — what may run without asking runs, everything else is reported rather than performed. This means a timed run can do strictly less than something typed interactively, which is the opposite of how cron usually works.

## Tool Set and Worker Delegation

Talos ships 32 gated tools across three effect classes:

- **18 read tools** — browsing, web search, file reading, vault access, image/audio/video perception, session search
- **5 write tools** — file write (with snapshot for undo), vault notes, skill writing, speech synthesis
- **9 exec tools** — sandboxed shell (`bubblewrap` on Linux, `sandbox-exec` on macOS), remote SSH execution, HTTP requests, git network operations, and worker delegation tools

Worker delegation (`delegate_code`, `delegate_dag`, `delegate_agy`, `delegate_codex`) hands bounded coding tasks to a confined Claude or Codex worker process running in a UID-separated disposable workspace. MCP integration is routed through the claude-worker seam — Talos itself never speaks MCP; the child worker does, and which servers may exist is an operator decision declared in a gitignored registry file.

## Channels and Identity Model

Every inbound channel fetches rather than listens — Telegram long-polls, mail pulls over IMAP, WhatsApp uses an operator-controlled SSH broker queue. No port is opened. Identities are channel-qualified: `telegram:123456789` and `cli:1000` are distinct even if they represent the same person. The agent ships with zero allowed identities; `TALOS_ALLOWED_PRINCIPALS` must be set explicitly or the agent refuses to start.

## Update: v0.19.19-alpha

The latest release (v0.19.19-alpha, published 2026-09-18) reflects active development. Recent additions documented in the README include: sandboxed shell execution, streaming replies, timed runs under an unattended ceiling, announced plans that tighten rather than widen a run, read-only delegation, a render-only browser with DNS resolver caging, media tools (image, audio, video frame), keyless web search via DuckDuckGo, mail as a second inbound channel, MCP over the claude-worker seam with an operator-owned registry, WhatsApp through an operator-controlled broker, and skill writing gated behind mandatory human approval. A per-provider credential model was also introduced to fix a credential disclosure bug where a single key field was shared across providers.

## Features
- Deterministic permission kernel with ALLOW/NEEDS_HUMAN/DENY verdicts
- 32 gated tools across read, write, and exec effect classes
- Sandboxed shell execution (bubblewrap on Linux, sandbox-exec on macOS)
- Capability tokens bound to exact arguments, valid once for 30 seconds
- Autonomy dial (0-5) that can only tighten, never loosen
- Unattended ceiling converts NEEDS_HUMAN to DENY for timed/background runs
- Worker delegation to confined Claude and Codex workers
- MCP integration via claude-worker seam with operator-owned registry
- Multi-channel support: terminal, Telegram, email (IMAP), WhatsApp (SSH broker)
- Zero default identities — TALOS_ALLOWED_PRINCIPALS must be set explicitly
- Render-only browser with DNS resolver caging against rebind attacks
- Announced plans that tighten step budgets rather than widen them
- Verifiable audit trail with write-ahead intent logging
- /undo command with file snapshot rollback
- Background tasks with independent cancellation and unattended ceiling
- Conversation memory with bounded history and middle-summarization
- Skill writing gated behind mandatory human approval
- 254 adversarial red-team cases run on every install and update
- 2817 unit tests verified by installer
- Per-provider credential model with fail-closed key resolution
- Keyless web search via DuckDuckGo by default
- Local audio transcription with faster-whisper
- Local speech synthesis with piper
- Video frame extraction via ffmpeg
- /policy dry-run command to preview kernel verdicts without executing
- Verifiable event log with chain digest and anchor pinning

## Integrations
Claude (Anthropic API), Claude CLI, Codex CLI, OpenAI API, Telegram Bot API, IMAP email, WhatsApp (Cloud API and SSH broker), DuckDuckGo (ddgs), Brave Search API, MCP servers (operator-configured), bubblewrap (Linux sandbox), sandbox-exec (macOS), ffmpeg, faster-whisper, piper, SSH, Git

## Platforms
CLI, API, LINUX, MACOS

## Pricing
Open Source

## Version
v0.19.19-alpha

## Links
- Website: https://talos-agent.ch
- Documentation: https://talos-agent.ch/docs/
- Repository: https://github.com/talos-kernel/Talos
- EveryDev.ai: https://www.everydev.ai/tools/talos-agent