Talos

KO | EN

gitlite — search

#terminal #hacktoberfest #editor #javascript #agents #github #http #golang #anthropic #go

(★ 9)

Self-hosted AI agent for terminal and Telegram, with Claude/Codex workers, live activity and a deterministic permission kernel.

File Explorer

ZIP Download

- - bug_report.md
  - config.yml
- - ci.yml
- PULL_REQUEST_TEMPLATE.md
- talos-character.png
- talos-hero.png
- talos-icon-128.png
- talos-icon-256.png
- talos-icon-512.png
- talos-icon-64.png
- talos-icon.png
- talos
- daily-reflection.json
- mail-triage.json
- morning-briefing.json
- skill-distillation.json
- weekly-review.json
- computer-cloud-init.json
- computer-requirements.in
- computer-requirements.lock
- computer-setup.py
- README.md
- talos-anchor.service
- talos-anchor.timer
- talos-briefing.service
- talos-briefing.timer
- talos-browser-keeper.service
- talos-claude-worker.service
- talos-computer-api.service
- talos-computer-egress.service
- talos-computer-vm.service
- talos-computer-web.service
- talos-dashboard.service
- talos-guest-browser.service
- talos-model.service
- claude-worker.md
- codex-worker.md
- command-compatibility.md
- computer.md
- dashboard.md
- media-delivery.md
- model-worker.md
- verification.md
- whatsapp-broker.md
- agent-intelligence.json
- - README.md
  - status-server.py
  - tailnet-status.sh
- entities.json
- mcp-servers.json
- - test_desktop_runtime.py
  - test_desktop_state.py
- build_app.py
- desktop_connections.py
- desktop_hermes.py
- desktop_runtime.py
- desktop_state.py
- Package.resolved
- Package.swift
- README.md
- backup-data.sh
- check-public-hygiene.py
- deploy-pi.sh
- deploy-site.sh
- sync-public.sh
- - apple-touch-icon.png
  - favicon.ico
  - icon-192.png
  - icon-512.png
  - LOGO-README.md
  - og-logo.png
  - sigil-78.png
  - talos-abnahmebogen.png
  - talos-app-icon.svg
  - talos-lockup-dark.svg
  - talos-lockup-light.svg
  - talos-lockup-mono-invers.svg
  - talos-lockup-mono.svg
  - talos-mark-dark.svg
  - talos-mark-light.svg
  - talos-mark-micro.svg
  - talos-mark-mono-invers.svg
  - talos-mark-mono.svg
  - talos-mark.svg
  - talos-wordmark-dark.svg
  - talos-wordmark-light.svg
  - talos-wordmark-mono.svg
- - index.html
- - cinzel-var.woff2
  - eb-garamond-var.woff2
  - inter-var.woff2
  - mono-var.woff2
  - sometype-mono-italic.woff2
  - sometype-mono-var.woff2
  - vt323.woff2
- - index.html
- - index.html
- - index.html
- - index.html
- .htaccess
- console.html
- index.html
- install.sh
- interface.css
- interface.js
- llms.txt
- README.md
- robots.txt
- sitemap.xml
- status.json
- talos-hero.jpg
- talos-icon.png
- - __init__.py
  - bridge.py
  - browser.py
  - cli.py
  - client.py
  - contract.py
  - egress.py
  - guest.py
  - observation.py
  - presentation.py
  - ready.py
  - service.py
  - state.py
  - web.py
- __init__.py
- __main__.py
- agent_loop.py
- anchor.py
- api_reasoner.py
- apiclient.py
- approval.py
- askcli.py
- attachment.py
- autonomy.py
- background.py
- blueprints.py
- briefing.py
- browser.py
- capability.py
- catalog.py
- channel.py
- chatcli.py
- claudejobs.py
- claudeworker.py
- cli.py
- cli_activity.py
- codexworker.py
- command_floor.py
- commands.py
- conductor.py
- config.py
- configcli.py
- consult.py
- continuity.py
- crashreport.py
- credentials.py
- cron.py
- customproviders.py
- dag.py
- dashboard.py
- dashboard_assets.py
- distill.py
- doctor.py
- documents.py
- errors.py
- evaluation.py
- eventlog.py
- eventscli.py
- executor.py
- fallback.py
- frames.py
- gitops.py
- health.py
- hearing.py
- identity.py
- instructions.py
- intelligence.py
- lessons.py
- mail.py
- manifest.py
- mcpservers.py
- media_cleanup.py
- mediaformat.py
- memory.py
- metrics.py
- modelinfo.py
- models.py
- modelworker.py
- notify.py
- oauth.py
- outcome.py
- plan.py
- policy.py
- proposal.py
- provider.py
- provider_errors.py
- question.py
- reasoner.py
- recall.py
- recovery.py
- redirect.py
- remedy.py
- remoteexec.py
- report.py
- review.py
- routine.py
- run_control.py
- sandbox.py
- schedule.py
- scheduler.py
- schema.py
- setup_wizard.py
- skills.py
- skillwrite.py
- snapshot.py
- speech.py
- standing.py
- stream.py
- subagent.py
- task_approval.py
- telegram.py
- terminalui.py
- tgmarkup.py
- tools.py
- transcript.py
- trust.py
- updater.py
- usage.py
- ux.py
- vault.py
- verifier.py
- vision.py
- wabroker.py
- web.py
- whatsapp.py
- worker.py
- working_display.py
- computer_browser_e2e.py
- computer_keyboard_e2e.py
- computer_view_e2e.py
- test_agent_consult.py
- test_agent_loop.py
- test_agy_jobs.py
- test_anchor.py
- test_api_reasoner.py
- test_apiclient.py
- test_approval.py
- test_approval_prompt.py
- test_attachment.py
- test_attended_autoapprove.py
- test_autonomy.py
- test_background.py
- test_background_model_router.py
- test_background_telegram_e2e.py
- test_blueprints.py
- test_briefing.py
- test_browser.py
- test_browser_contract.py
- test_browser_mcp.py
- test_capability.py
- test_catalog.py
- test_chat_command_compatibility.py
- test_chatcli.py
- test_claude_config.py
- test_claude_jobs.py
- test_claude_policy.py
- test_claudeworker.py
- test_cli.py
- test_cli_activity.py
- test_cli_error_output.py
- test_cli_onboarding.py
- test_codex_jobs.py
- test_command_floor.py
- test_commands.py
- test_composition_wiring.py
- test_compression.py
- test_computer.py
- test_computer_cli.py
- test_computer_observation.py
- test_computer_service.py
- test_computer_tabs.py
- test_computer_web.py
- test_conductor.py
- test_continuity.py
- test_crashreport.py
- test_credentials.py
- test_cron.py
- test_custom_providers.py
- test_dag.py
- test_dashboard.py
- test_delegate_steer.py
- test_deletable_roots.py
- test_distill.py
- test_documents.py
- test_ephemeral_telegram.py
- test_errors.py
- test_eventlog.py
- test_eventscli.py
- test_executor.py
- test_fallback.py
- test_first_run.py
- test_gitops.py
- test_health.py
- test_hermes_reasoner.py
- test_identity.py
- test_instructions.py
- test_intelligence.py
- test_intelligence_evaluation.py
- test_introspection.py
- test_lessons.py
- test_mail.py
- test_mcp_servers.py
- test_media.py
- test_memory.py
- test_memory_wiring.py
- test_metrics.py
- test_mission_panel.py
- test_model_catalog_refresh.py
- test_model_conductor.py
- test_model_overrides.py
- test_modelworker.py
- test_multiline_stop_and_delegation.py
- test_notify.py
- test_oauth.py
- test_operator_recovery_integration.py
- test_outcome.py
- test_plan.py
- test_policy.py
- test_policy_exec.py
- test_policy_targets.py
- test_proposal.py
- test_proposal_recovery.py
- test_provider.py
- test_provider_resilience.py
- test_public_hygiene.py
- test_question.py
- test_question_wiring.py
- test_queue_lifecycle.py
- test_recall.py
- test_recovery.py
- test_redirect.py
- test_redirect_wiring.py
- test_remedy.py
- test_remoteexec.py
- test_report.py
- test_requirements_lock.py
- test_requires_env.py
- test_review.py
- test_routine.py
- test_sandbox.py
- test_schedule.py
- test_scheduler_dispatch.py
- test_setup_wizard.py
- test_site_claims.py
- test_skills.py
- test_skillwrite.py
- test_snapshot.py
- test_standing.py
- test_standing_flow.py
- test_stopall.py
- test_stream.py
- test_streaming_reply.py
- test_subagent.py
- test_task_approval_flow.py
- test_task_approval_telegram_e2e.py
- test_telegram.py
- test_telegram_progress_updates.py
- test_telegram_ux.py
- test_tgmarkup.py
- test_tools.py
- test_transcript.py
- test_trust.py
- test_updater.py
- test_usage_attribution.py
- test_vault_tools.py
- test_verifier.py
- test_version.py
- test_wabroker.py
- test_web.py
- test_whatsapp.py
- test_work_trail.py
- test_worker.py
- test_worker_binary_config.py
.env.example
.gitattributes
.gitignore
CHANGELOG.md
CLAUDE.md
CONTRIBUTING.md
DESIGN.md
e2e.py
GOVERNANCE.md
LICENSE
NOTICE
PRODUCT.md
README.md
redteam.py
requirements-dev.lock
requirements-dev.txt
requirements.lock
requirements.txt
SECURITY.md
SOUL.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">TALOS</h1>

An autonomous agent you can hand a shell to, because it can prove what it will not do.

<a href="https://talos-agent.ch">talos-agent.ch</a> ·
 <a href="https://talos-agent.ch/docs/">Field manual</a> ·
 <a href="CHANGELOG.md">Changelog</a>

<img src="https://img.shields.io/badge/tests-2758-2e7d32.svg" alt="Tests">
 <img src="https://img.shields.io/badge/red%20team-254%2F242-2e7d32.svg" alt="Red team">
 <img src="https://img.shields.io/badge/gate%20path-919%20lines-8a4318.svg" alt="Gate path">
 <img src="https://img.shields.io/badge/tools-31%20gated-8a4318.svg" alt="Tools">
 <img src="https://img.shields.io/badge/default%20identities-0-c62828.svg" alt="Default identities">
 <img src="https://img.shields.io/badge/python-3.11%2B-1565c0.svg" alt="Python">
 <img src="https://img.shields.io/badge/licence-MIT-616161.svg" alt="MIT">

---

Talos runs on your own machine, takes instructions over a chat channel, thinks through a
language model, and executes tools — but only after a deterministic security kernel has
ruled on the action. **The model proposes. It never decides.**

```
   message ──▶ event log ──▶ reason ──▶ ╔══════════╗ ──▶ capability ──▶ execute
                                        ║  KERNEL  ║        token          │
                                        ╚══════════╝                       ▼
                                             ▲                     verify ──▶ receipt
                              the only place effects are authorised
```

| | |
|---|---|
| **Authority** | a token bound to exact arguments — valid **once**, for **30 seconds** |
| **A tool without a target extractor** | `DENY` by construction, not by a rule someone wrote |
| **Ships with** | **zero** identities that may command it |
| **The shell** | sandboxed, or it refuses to run at all |

```bash
curl -fsSL https://talos-agent.ch/install.sh | less   # read it first
curl -fsSL https://talos-agent.ch/install.sh | sh     # then run it
```

The installer verifies the signature and the checksum, runs the full suite — and then
**stops**. Nothing starts listening until you say so.

---

<details>
<summary>Contents — twenty-two sections, in the order they matter</summary>

**Start here**
[Why this exists](#why-this-exists) ·
[What it does not do](#what-it-does-not-do) ·
[Install](#install)

**Using it**
[A session in the terminal](#a-session-in-the-terminal) ·
[Work on the side](#work-on-the-side) ·
[What it remembers](#what-it-remembers) ·
[Seeing what it did](#seeing-what-it-did) ·
[Commands](#commands)

**How it holds**
[How the kernel decides](#how-the-kernel-decides) ·
[The autonomy dial](#the-autonomy-dial) ·
[Timed runs](#timed-runs) ·
[Announced plans](#announced-plans) ·
[The browser that only reads](#the-browser-that-only-reads) ·
[Delegating](#delegating) ·
[WhatsApp through your own broker](#whatsapp-through-your-own-broker) ·
[The MCP registry](#the-mcp-registry) ·
[Identity](#identity)

**Evidence**
[What a run looks like](#what-a-run-looks-like) ·
[Audit trail](#audit-trail) ·
[Tools](#tools) ·
[Architecture](#architecture) ·
[Roadmap](#roadmap)

</details>

## Why this exists

Every capable agent eventually asks for shell access. At that moment you are trusting a
language model with your machine, and the usual answers are unsatisfying: either it asks
you to confirm everything (and you stop reading the prompts by day three), or it runs free
behind a regex blocklist and you hope.

Talos takes a third position. **Authority is a token, not a list.** Every effect is
authorised individually, bound to its exact arguments and targets, valid once, for thirty
seconds. Forgetting to call the gate does not produce an unchecked effect — it produces no
effect at all, because the raw runners are unreachable without a token.

That design is testable, and it is tested: 254 adversarial scenarios run on every change and
try to get an effect past the kernel. They are in [`redteam.py`](redteam.py). Read them
before you trust anything written above.

## What it does not do

Stated plainly, because a security claim without its limits is marketing:

- **`run_shell` needs a sandbox the platform can actually provide.** It runs under
  bubblewrap on Linux and `sandbox-exec` on macOS. Where neither is available it *refuses*
  rather than running unprotected, so on such a host the shell tool is simply unavailable
  until the operator overrides it on purpose (`TALOS_SANDBOX_ALLOW_UNCONFINED=1`).
- **It is not a multi-tenant security boundary.** One operator, one machine. Anyone who can
  run code in the process can reach the token mint.
- **There is no gateway, no setup portal and no `config.yaml`.** Each was considered and
  left out, for the same reason. A gateway terminates foreign identities and then *claims*
  `channel:id` to the kernel instead of proving it. Identity checking would then hang on a
  component outside the kernel. A web portal is a network service with its own
  authentication, so it is a second source of permission beside the allowlist. And a
  second config file would be two truths about who may command it, when the path floor
  protects exactly one. What weakens it is not the number of commands. It is a second
  way in.
- **It does not defend against a malicious model.** It defends against a *mistaken* one,
  and against prompt injection arriving through tool output. Those are different threats.
- **Search needs no account.** Without `TALOS_BRAVE_API_KEY` it used to refuse; now it
  answers over DuckDuckGo (the `ddgs` package, imported at call time). A key decides
  *which* provider answers, not *whether* one does.
- **It has three ways in, and all of them fetch** (Telegram long-polling, mail over
  IMAP, the WhatsApp broker queue over SSH). That is the rule, not an accident: an
  inbound webhook would need a port the world can reach, which turns "outbound only"
  into "publicly reachable". Mail sits at `Trust.ASK` — an address proves no account,
  so it may ask and receive answers but never approve anything. WhatsApp over the
  Cloud API stays delivery-only for the same reason; the broker channel below is the
  one that fetches.
- **It hears locally or not at all.** `hear` transcribes a recording with faster-whisper
  on the machine it runs on — what was said is often the most private thing in a day, and
  sending it to somebody else's model to be understood is the one place where "runs on your
  machine" would be traded for convenience. It is an ordinary `READ` with the file as its
  target, so a recording under `~/.secrets/` is refused without the module knowing anything
  about secrets. The model loads on first use, not at boot.
- **It can see, on a real file.** A photo you send is fetched into `workspace/inbox/` and
  the note carries the path, so `see_image` has something to point at — and the kernel has
  a target to judge. The fetch asks the allowlist first: the channel parses updates before
  the kernel has ruled on identity, so an unconditional fetch would let anyone who finds
  the bot write files to your disk. `speak` writes a WAV offline (piper).
- **It can take one still out of a video.** `grab_frame` runs ffmpeg once and puts a
  single picture in the inbox; `see_image` looks at it afterwards. Both the video and the
  picture are targets the kernel judges, so a video under `~/.secrets/` is refused exactly
  like a recording — without that, calling a file a video would have been the way around
  the secret floor. Where the picture lands is derived by the kernel, not chosen by the
  model, and it is deliberately one frame rather than a series: fanning ffmpeg out over a
  whole film and encoding every frame is how a small machine ends up unreachable.
- **It does not generate pictures or video, on purpose.** Reading one is a `READ` with a
  target; making one is a paid call to somebody else's model, and it was removed rather
  than kept around waiting for credit. Seeing stays.

## Install

Requires Python 3.11+ on Linux or macOS and a model connection: your own API key,
or an installed, signed-in Claude or Hermes CLI. The setup wizard offers the
connections available on your machine.

```bash
git clone https://github.com/talos-kernel/talos.git
cd talos
python3 -m venv .venv && . .venv/bin/activate
pip install --require-hashes -r requirements.lock -r requirements-dev.lock
export PATH="$PWD/bin:$PATH"              # makes `talos` available in this shell

python -m talos setup terminal           # local identity + model; no Telegram needed
python -m talos chat                     # your first conversation
```

Prefer Telegram? Run the bot wizard, then start the service:

```bash
python -m talos setup                    # token, identity and model
python -m talos                          # run the Telegram agent
```

`setup` proves what it can rather than trusting what you type: the token goes to `getMe`,
and your identity comes from a **real message you send your own bot** — not from a number
you copy. A wrong token announces itself on the first poll; a wrong identity does not, and
a stranger's identity never does. Setup preserves unrelated settings and writes each
section atomically with mode 0600. It prints the configuration path and the next command.
Use `talos doctor` for missing prerequisites and `talos help <command>` for command help.
A running service needs a restart after changing its file settings.

Later, a single part can be redone without repeating the rest:

```bash
python -m talos setup model              # switch what it thinks with
python -m talos setup mail               # add the second way in (IMAP)
python -m talos config list model        # find settings by name or description
python -m talos config describe TALOS_STATUS_STYLE
python -m talos config set TALOS_STATUS_STYLE expressive
python -m talos config set TALOS_MODEL claude-fable-5-1
python -m talos config set TALOS_MODEL_OVERRIDES '{"local-model": {"context_window": 128000}}'
                                         # never a provider, url or key; shown as your word
python -m talos models --refresh         # ask each provider what it offers now
python -m talos status                   # what it did last
python -m talos chat                     # a session here; approvals at a terminal
python -m talos ask "how many …?"        # one turn from here, answer on stdout
python -m talos events --tool run_shell  # what happened — read-only, filterable
python -m talos why 4831                 # why that was allowed or refused
python -m talos review                   # what this installation should change
python -m talos report --out audit.txt   # what was done and what was refused
```

With `TALOS_STATUS_STYLE=expressive`, Telegram keeps one live activity card with
tool icons, elapsed time and an outcome for each step. It updates in place; the
answer stays separate. Tool and plan JSON is hidden even after a prose introduction.
Completed answers stay formatted after approval buttons, and Markdown tables become
compact labelled rows. Approval prompts keep the exact command visible.
`/stop` interrupts the run and `/log` opens its receipts. A finished conversation
does not imply that a delegated background job has finished.

A full walkthrough — install, identity, the session, every command, and the ones that are
missing on purpose — is at **[talos-agent.ch/docs](https://talos-agent.ch/docs/)**.

`ask` is not a second way in. It is a **channel like any other**, with the same protocol
and no special right. Two consequences follow, and both are the point of it. While the
allowlist is empty the local caller is admitted as `cli:<uid>` automatically, so the first
run works. The moment the list names one identity it becomes exhaustive, and the uid must
appear as `cli:<uid>` exactly like a Telegram number. A shell next to the agent is not an
argument for granting it anything. And the turn always runs under
the **unattended ceiling**: a one-liner waits for nothing, so `NEEDS_HUMAN` becomes `DENY`
and says so. Approve in the chat, where somebody is actually looking.

It also refuses to run inside the agent's own sandbox. Otherwise the agent could start
`talos ask` from its shell and give itself orders — no channel, no foreign identity,
nobody reading along.

## A session in the terminal

`ask` answers once and leaves. For anything that takes more than one turn there is
`talos chat` — the same channel name, the same identity, the same conductor, the same
kernel. The loop is line for line the one the service runs for Telegram; only the messages
come from `stdin` instead of `getUpdates`.

```
$ talos chat
Talos 0.9.2-alpha  ·  anthropic/claude-opus-4  ·  autonomy 3
speaking as cli:1000  ·  approvals possible — you are at a terminal
/help for commands, `exit` to leave

› what changed in the log today?
```

The second line is the one to read: it says, before you ask for anything, whether an
approval is even possible here — so a refusal later is explained in advance rather than
guessed at.

**The unattended ceiling hangs on the terminal, not on the command.** This was the
contested decision. Applying `ask`'s rule to an interactive session would mean `chat`
could never write anything; dropping it would mean `talos chat < jobs.txt` in a cron job
looks exactly like a human. So it is measured rather than claimed: **both `stdin` and
`stdout` must be a real tty**. A pipe, a redirect, a cron run has none, and there
`NEEDS_HUMAN` becomes `DENY` as before. Checking only `stdin` would let
`talos chat > out.log` pass as attended — nobody reads a question written to a file.

The in-session commands are the same ones the messenger has, through the same command
centre. A second vocabulary that only worked here is exactly the duplication this project
has paid for elsewhere.

## Work on the side

Some questions take two minutes, and the conversation should not stand still for them.

```
› /background go through /var/log and summarise today's errors

Background #1 started: go through /var/log and summarise today's…
  id bg_a1b2c3d4e5f6 · runs unattended, so anything needing approval is refused
```

**A background task is a scheduled run, not a helper carrying your rights.** That is the
whole security decision, and it avoids inventing a new concept. It is *not* a subagent:
that one is born from model text and may therefore only read. Here a human typed the task,
so its origin is the same as any other message. But nobody is sitting in front of it — so
the ceiling from the timed run applies, and anything that would need approval is refused.
Putting a question into a chat where a different conversation is running is the most
reliable way to land a "yes" on the wrong thing.

Its context is **empty**: the task and nothing else. Two runs sharing one history write
into each other, and afterwards nobody can say which of them said what. The result does not
flow back into the history either — it arrives as its own message, marked as a report.

If no ceiling is wired, the task is **refused** rather than run uncapped. A forgotten
parameter may only ever allow less.

A running background task can be **steered**: `delegate_steer` queues a course correction,
and the task reads it at its next step boundary — the same seam where a typed correction
enters a foreground run, only from its own mailbox. The instruction arrives as a framed
turn ("no additional rights"); every tool call it provokes passes the same kernel under
the same ceiling. Only the person and conversation that started the task may steer it,
a delegated run may not steer at all, and anything without a step boundary in this
process — a synchronous `delegate`, a worker job, a timed run — answers with a refusal
rather than a pretend "ok".

And everything stoppable stops at once: `/stopall` (also `/estop`) aborts the running
thought, drains the queue, detaches every background task at its next step and discards
its report, and **discards** every pending approval — it never approves one. Timed runs
stay; a stop that deleted timers would create the next incident while ending this one.
The reply is an honest balance per category, and a second `/stopall` says so.

## What it remembers

The conversation is kept per channel, in memory only, bounded by turns and by characters.
When the bound is reached the **middle is summarised** and both ends stay verbatim — the
head usually carries the actual task, the tail whatever "and that too" refers to.

```
You:                  set up the backup for the NAS
Agent:                done — see /etc/backup.d
Earlier (summarised): discussed retention, settled on 30 days; the NFS
                      mount needed the hard option
You:                  and add the offsite copy
```

The summary is labelled as one and never disguised as a verbatim turn — a summary that
looks like something actually said is a claim about words nobody used, and the model could
quote it back as if it were. It goes into the prompt as history, never into the standing
instructions, and the transcript reaches the summariser explicitly framed as *data*:
otherwise "summarise this" is the most convenient place for an injected line to become an
instruction, and a permanent one, because the summary stays.

⚠️ **The bound is not a comfort feature.** If summarising fails, the oldest turns are
dropped as before. A history that kept growing after a failed summary would turn a cost
question into a leak — what was said weeks ago would go out again.

## Seeing what it did

The thin feeling with an agent like this does not come from missing verbs. It comes from
not being able to see what it did and why. Both of these are **read-only**:

```bash
python -m talos events --tool run_shell   # what happened, filterable
python -m talos why 4831                  # why that was allowed or refused
```

`why` names the verdict, the rule that produced it, and the targets it applied to — and
states that those targets were *derived from the real arguments*, never taken from what
the model wrote. Then it shows the rest of the same run, because "refused, and then?" is
the question that makes people stop reading logs.

There is deliberately no `talos undo` beside them. `/undo` exists, and since `talos chat`
it is reachable from the command line through the same path the messenger uses. A second
one would be convenience against the design.

**`config set` refuses two whole classes of key**, and that is the point of it. Secrets
never go on a command line — that lands them in the shell history and in `ps` for every
user of the machine. And `TALOS_ALLOWED_PRINCIPALS`, `TALOS_SECRETS_ENV`,
`TALOS_MAIL_AUTHSERV_ID`, every `TALOS_BASE_URL_<PROVIDER>` and
`TALOS_WEB_ALLOWED_ADDRESSES` are not settings but *policy*:
whoever writes them does not have to talk the kernel into anything, they reconfigure it.
Not settable, not even with a confirmation — a confirmation is exactly what gets clicked
away. `config get` answers `[REDACTED]` for a secret **whether it is set or not**, so the
command cannot be used to find out which doors a machine has.

**A key belongs to one provider.** There is no single `api_key` and no single base url;
`credentials.py` keeps a route per provider — key *and* address in one piece, resolved at
the moment of the call rather than frozen when the reasoner was built, because `/model`
switches providers while the process keeps running. If the selected provider has no key,
the switch is refused and the previous one stays active: no other provider's key stands
in for it. Until 2026-08-05 one field held `ANTHROPIC_API_KEY or OPENAI_API_KEY` for every
provider, so choosing `openai-api` sent an Anthropic key to OpenAI as a bearer token — a
credential disclosure that looks like a typo, because the wrong recipient answers `401`.

**There is no default allowlist.** `TALOS_ALLOWED_PRINCIPALS` must name your identity or
the agent refuses to start. A shipped default would be a backdoor printed in the source.

## How the kernel decides

`PolicyKernel.decide()` returns exactly three verdicts — `ALLOW`, `NEEDS_HUMAN`, `DENY` —
and the executor calls no runner before it has one.

| Class | Examples | Verdict |
|---|---|---|
| Ordinary work | `ls`, `git status`, tests, builds, writes inside the workspace | **runs** |
| Risky but recoverable | `curl \| sh`, `git reset --hard`, `rm -rf <path>` | asks you |
| Persistence & secrets | `.bashrc`, systemd units, `~/.ssh`, the agent's own source | asks you |
| Catastrophic | `rm -rf /`, `mkfs`, `dd` to a block device, fork bomb, reboot | **refused** |
| Secret reads, system paths | `cat /etc/passwd`, anything under `/etc /boot /usr /bin` | **refused** |

`DENY` returns **before** the approval check, so a "yes" cannot reach a hardline rule.
Approvals are one-shot, five-minute TTL, bound to the exact request, and re-verified against
file hashes immediately before execution (TOCTOU).

Targets are derived from real tool arguments, never from a field the model could omit. A
tool without a target extractor is `DENY` by construction.

## The autonomy dial

`/autonomy 0..5` sits above the kernel and **can only tighten, never loosen**. Level 5 is
exactly the unfiltered kernel — not "anything goes". A dial that granted rights would be a
second source of permission next to the kernel, which is the thing this design removes.

| Level | Reads | Writes | Shell |
|---|---|---|---|
| 0 | refused | refused | refused |
| 1 | asks | refused | refused |
| 2 | free | refused | refused |
| 3 | free | asks | asks |
| 4 | free | free in workspace | asks |
| 5 | free | kernel decides | kernel decides |

The level survives restarts because it lives in the event log. An unreadable log drops to
level 0, not to the last convenient value.

## Timed runs

`/every 90 <task>` repeats on an interval; `/every 0 8 * * MON-FRI <task>` takes a cron
expression, because an interval can say "every 90 minutes" but never "weekdays at 08:00".
An expression is a better clock, not an extra permission — what runs afterwards passes the
same kernel.

And it passes one ceiling more. During an unattended run `NEEDS_HUMAN` becomes `DENY`:
what may run without asking runs, everything else is **reported rather than performed**.
Not parked until morning either — an approval question whose occasion is six hours old is
how reflexive clicking starts. So a timed run may do strictly *less* than something you
typed, which is the opposite of how cron usually works.

A blueprint can give a timed run a **memory** and a **probe**. With `continuity: true`
the previous result is placed in front of the task as data — "yesterday 91 %, and
today?" — and a run that ends in the same failure as its predecessor is logged instead
of repeated into the chat. With `monitor: true` and a `probe` (a shell command) the
probe is read *before* the model is asked: an unchanged output means no model call at
all, with `schedule.skipped_unchanged` in the log. The probe is an ordinary `run_shell`
of the task's principal through the same executor, kernel and sandbox, under the same
unattended ceiling — no new permission. And a probe that fails, whatever the reason,
fires the run: a broken sensor must not be the way to silence a watcher.

## Announced plans

For a task with several steps the agent may announce the sequence before it starts:

```
≡ 3 steps — collect the log, find the failing service, report
```

The announcement changes nothing about permission. Every step still passes the kernel one
at a time, exactly as if it had been asked for alone, and a step that needs approval still
stops and asks. What the announcement does is **bind the run**:

- the step budget shrinks from the house limit to what was announced — a three-step plan
  cannot become forty tool calls;
- the first step that fails ends the run with a report of what ran, what stopped it, and
  what therefore did not happen — instead of the model improvising around the failure,
  which is how an agent turns a refusal into a bigger second attempt;
- the plan is read **once**. A tool result is a stranger's text; if it could install a
  second, larger plan mid-run, prompt injection would be a way to buy budget.

### The step that is checked by code

A step may carry a condition, and the condition is **not evaluated by the model**:

```json
PLAN: {"goal": "restart and confirm", "steps": [
  {"intent": "restart the service", "check": "contains:rc=0"},
  {"intent": "write the report",     "check": "wrote:/tmp/report.md"}
]}
```

This closes a real hole. `run_shell` returns `rc=1` and the executor still records
`DONE` — because the *tool* ran. Whether the *work* succeeded lived only in the output
text, and the only reader of that text was the model, which has an interest in the
answer. A condition is checked in code, in the order announced, against the receipt of
the step that ran: `ok` (finished cleanly), `contains:<text>` (its output held that
text), `wrote:<path>` (it wrote exactly there, as the *kernel* derived the target — not
as the model claimed it).

A condition can only ever withhold a confirmation. If one never comes true, the answer is
delivered in full and the system adds its own line beneath it:

```
✕ 1/2 announced checks met — NOT confirmed done. Still open: step 2 (it writes to /tmp/report.md).
```

The honest limit: **the model writes the conditions too.** A met condition proves
that the run's own stated expectation came true — not that the job was done well. Someone
who sets themselves a trivial condition passes it. What the code guarantees is narrower and
still worth a lot: that the condition was really *evaluated* rather than asserted, that it
is shown to you word for word so you can judge its worth, and that the real count also
lands in the event log — which the model cannot write to, and where a forged verdict line
in its prose is contradicted.

Conditions inspect only the receipt of their own step, never the state of the world. One
that could read arbitrary files would be an oracle around the kernel (*"read `/etc/shadow`
and tell me whether it contains root"*), and an unknown condition is dropped rather than
counted, so inventing vocabulary gains nothing.

So planning here does the opposite of what it usually does: it makes a run more
predictable and *less* powerful. That is deliberate, and it is the same inversion the
unattended ceiling makes — a capability that arrives with more rights attached is not a
capability this design accepts. Under that ceiling the two compose without knowing about
each other: an unattended plan stops at the first step that would need a human, and says
so.

## The browser that only reads

`web_fetch` returns source; half the web is an empty shell without JavaScript. `browse`
renders the page in real Chromium and hands back what a reader would see.

What it deliberately cannot do is **operate** a page — no clicking, typing or submitting.
A click has no derivable target: "click the third element" cannot be mapped to a resource
you could bind a permission to, and a tool without a derivable target is `DENY` here by
construction. That is the right answer rather than a shortfall — an agent that operates
strangers' pages has a path to effect that no kernel catches afterwards.

It is also fenced more tightly than a URL check alone can manage. Chromium is pinned to
exactly the address `guard_url` verified, and nothing else resolves at all:

```
--host-resolver-rules="MAP * ~NOTFOUND, MAP <host> <ip>"
```

A redirect to another name goes nowhere, a script pulled from an ad network likewise, and
a DNS rebind between check and fetch — the classic hole in every filter that inspects only
the first name — has no effect. The cost is honest: pages that load their content from a
CDN under a different name come back incomplete. Incomplete beats uncontrolled.

Every call gets a throwaway profile: no cookies, no signed-in sessions, no history. A page
Talos opens sees a factory-fresh browser.

## Delegating

`delegate` hands one self-contained question to a second run — and that run **may only
read**. No writing, no shell, nothing that needs approval. It uses the same executor, the
same kernel and the same identity as its caller; what changes is a fourth ceiling that
turns everything except reading into `DENY` for as long as it lasts.

The reason is the same one that shapes timed runs. A delegated run is born from *model
text*, not from someone typing. Giving it the rights of the run that started it would make
delegation the most convenient way to produce an effect nobody asked for — a second source
of permission wearing a different name. So delegation buys reach, never power: it is for
looking things up without filling the main run's context with the search. What comes back
is data, bounded like any tool result, never an instruction.

## WhatsApp through your own broker

The Cloud-API channel (`whatsapp.py`) can only deliver, because Meta's inbound path is a
webhook — and a webhook is a port the world can reach. The broker channel
(`wabroker.py`) gets inbound without breaking the rule: a listener on **an
operator-controlled WhatsApp broker reachable over SSH** appends the messages routed to
Talos to a JSONL queue, and Talos *pulls* that queue over SSH with a persisted byte
cursor. Every connection goes outward, to a machine the operator controls, with the
operator's own key. Nothing listens.

Replies go back the same way — through the broker's send script, base64-safe; files
travel as `scp` plus broker. The sender number comes out of the operator's own WhatsApp
account rather than a text field, so the channel carries `Trust.FULL`, and the
conversations live in the same `whatsapp:<number>` namespace as before. Three env vars,
all off by default: `TALOS_WA_BROKER_SSH` (the SSH target — empty means the channel does
not exist), `TALOS_WA_BROKER_QUEUE` and `TALOS_WA_BROKER_CLI_DIR`. Configured, the broker
wins over the Cloud-API variant: both are named `whatsapp`, and this is the one that
fetches. A failed poll is a loud `channel.error`, and the cursor never advances on
failure — silence would look exactly like an empty queue. Operator details:
[docs/whatsapp-broker.md](docs/whatsapp-broker.md).

## The MCP registry

MCP is shipped — over the claude-worker seam, not into the agent. Talos itself never
speaks MCP; the `claude -p` child inside a UID-separated worker job does, and Talos only
writes the MCP config and passes it through. Which servers may exist at all is an
operator decision, declared in `data/mcp-servers.json` (gitignored, fail-closed like
`entities.json`): `version: 1` mandatory, absolute commands only, an `env` field costs
the whole entry, sixteen servers at most. The socket frame carries server *names*, never
commands or args.

And it is gated twice: a server must appear in the registry file **and** in the worker's
`TALOS_CLAUDE_WORKER_MCP_SERVERS` allowlist, or the request is refused by name before any
job starts. There is no marketplace and no third-party code in the agent process — a
curated starting point is [examples/mcp-servers.json](examples/mcp-servers.json), the
full contract is [docs/claude-worker.md](docs/claude-worker.md).

## Identity

`SOUL.md` carries the agent's **name and character**. Its first heading is the name —
change `# TALOS` to `# ARGUS`, restart, and the agent is renamed everywhere, including the
header of the live display. There is no second place where the name lives.

`AGENTS.md` carries durable operating discipline; `USER.md` carries stable preferences
for the operator. All three reload on the next message, have explicit context limits, are
protected by the persistence floor, and survive updates as operator-owned state. Missing
`AGENTS.md` or `USER.md` is harmless; a missing or broken `SOUL.md` uses the safe fallback.

## What a run looks like

A plain question gets a plain answer — no status chrome. The moment a tool runs, one
message starts tracking it and stays afterwards as the receipt:

```
◉ Talos · 9s · step 2/100
✓ shell command  2s
▸ write note — disk.md
```

`◉` agent · `◈` thinking · `≡` plan announced · `▸` tool · `✓` done · `✕` failed ·
`⏸` waiting on you · `⛒` refused · `↩` rolled back. One glyph, one meaning, never in the prose of an answer.

## Audit trail

`exec.intent` is written **before** anything happens:

```
exec.intent → approval.parked → approval.granted → exec.intent → exec.result
```

A crash mid-action still leaves a trace. Every run carries the id of the token that
permitted it. `/log` shows the last effects, `/undo` rolls back the last file change.

## Tools

Thirty-one, and every one of them passes the same gate. There is no privileged tool and no
tool that skips the kernel — a tool without a target extractor is `DENY` by construction.

| | |
|---|---|
| `run_shell` | a command, sandboxed, or refused where no sandbox exists |
| `computer_run` / `computer_status` | guarded computer use: bounded desktop actions and their status, each step through the gate |
| `remote_exec` | a command on another machine over ssh — operator-allowlisted hosts, always a human's yes, standing rules bind to exact host+command |
| `http_request` | any REST API — read methods through the SSRF-hardened door, state-changing methods always a human's yes, binding to exact method+URL |
| `git` | clone / fetch / pull / push with credentials — every op a human's yes, binding to exact op+repo+remote; local git work stays in the sandboxed shell |
| `entity_status` | a known name resolved to an operator-configured fixed read-only probe |
| `read_file` / `write_file` / `undo_last` | ordinary work, with a snapshot behind the write |
| `browse` / `web_fetch` / `web_search` | render-only, guarded URL, keyless search by default |
| `see_image` / `grab_frame` / `hear` / `speak` | a picture, one still out of a video, a recording, a voice |
| `read_document` | a PDF, Word, Excel or PowerPoint file turned into text — locally, framed as untrusted |
| `vault_search` / `vault_get` / `vault_write_note` | a markdown knowledge base, if you point it at one |
| `session_search` | what was said in earlier turns |
| `delegate` | a sub-run that can only read |
| `delegate_code` / `delegate_dag` / `delegate_status` | a bounded coding job — or a small acyclic graph of them — for a confined Claude worker: opt-in, off by default, writes only into a kernel-derived disposable workspace |
| `delegate_agy` | the same confined worker's second backend (the agy CLI): same trust form and workspace, behind its own opt-in gates on agent and worker, no MCP |
| `delegate_codex` | bounded implementation and independent review with Codex: the same kernel and sandbox, isolated auth, verified stream completion and originating-chat notifications; [setup](docs/codex-worker.md) |
| `delegate_steer` | a course correction into a *running* `/background` task — a framed turn it reads at its next step, never a new right |
| `agent_consult` | bounded advice from a second, operator-configured agent — data, never permission |
| `ask_operator` | the one way it can ask you something on purpose |
| `skill_write` | a new skill, written exactly once — and never without a human's yes |

### Operator-owned entity knowledge

Talos ships with no real entity names, hosts or service units. To enable entity-aware
status checks, copy the neutral example and replace every placeholder with infrastructure
you control:

```bash
mkdir -p data
cp examples/entities.json data/entities.json
```

`data/entities.json` is runtime state: Git ignores it, updates preserve it, and Talos reads
it as context rather than authority. `entity_status` accepts only a configured entity name;
the fixed URL or systemd user unit comes from this file and cannot be supplied by the model.

### Skills it writes for itself

`skill_write` is the one write path into the skills directory — and the hardest gate in the
house. A skill is the strongest persistence there is: its text lands in *every* prompt from
the next turn on. So the tool is declared irreversible, the kernel answers `NEEDS_HUMAN`
without exception, and under the unattended ceiling that becomes `DENY`. It creates only —
never overwrites (atomically, not by looking first), never writes `allowed-tools` (a second
permission source next to the kernel), never anything that looks like a credential, and
never outside the skills root. Improving a skill means the operator deletes it first.

Two blueprints use it on a schedule. `skill-distillation` ("every sunday 20:15") reads the
week's event log and distils at most one repeated, proven workflow into a skill candidate —
written through `skill_write` when a human is there to approve, parked as a vault note under
`patterns/` when the unattended run is refused. And `daily-reflection` closes each day with
a look at the same log — verified live against a real installation, schedules and ceiling
included, not only in the suite.

There is no image generation. That is a decision, not a gap: an agent that can produce
photographs is a different conversation than one that can only look at them.

## Commands

**In a session** — the same set in the terminal and in the messenger, through one
command centre.

`/stop` `/stopall` `/queue` `/status` `/new` `/retry` `/background` · `/pending` `/approve` `/deny`
`/allowed` `/revoke` · `/log` `/undo` `/policy` `/autonomy` `/tools` `/whoami` `/version` ·
`/usage` `/model` `/reasoning` `/debug`

**On the command line** — thirteen, each answering a question an operator actually asks:

| | |
|---|---|
| `chat` | a session here; approvals at a terminal |
| `ask "…"` | one turn, for scripts and cron |
| `setup` · `doctor` · `config` · `models` | set it up, and find out why something won't work |
| `status` · `events` · `why <id>` | what it did, and why that was allowed or refused |
| `report` · `review` | a record someone else can read · what this installation should change |
| `update` · `version` | signature checked, tests first |

`/policy <path|command>` is a dry run: it calls `decide()` and shows the verdict without
executing anything. It is the fastest way to understand the kernel.

## Architecture

Small modules on purpose. The gate path (`policy.py`, 919 lines) has to be readable in one
sitting — a gate you cannot read is not a gate.

| Module | Role |
|---|---|
| `policy.py` | the kernel: target derivation, three verdicts |
| `capability.py` | tokens: mint, redeem, invalidate |
| `command_floor.py` | hardline and dangerous command detection |
| `approval.py` / `standing.py` | one-shot and standing approvals |
| `autonomy.py` / `trust.py` / `channel.py` | ceilings above the kernel |
| `executor.py` / `verifier.py` / `snapshot.py` | write-ahead execution, TOCTOU, undo |
| `conductor.py` / `agent_loop.py` / `worker.py` | orchestration |
| `plan.py` / `schedule.py` / `subagent.py` | announced sequences, timed runs, delegation — all only tighten |
| `web.py` / `browser.py` | the only door out: URL guard, then a resolver cage |
| `reasoner.py` / `provider.py` | pluggable model backends |
| `intelligence.py` / `evaluation.py` | bounded entity context, working state, factual review, adaptive reasoning and trace regression metrics |
| `credentials.py` | one route per provider — key *and* address, resolved at call time |
| `sandbox.py` | bubblewrap / `sandbox-exec`; refuses rather than running unconfined |
| `identity.py` / `ux.py` | name and glyphs |
| `telegram.py` / `mail.py` / `whatsapp.py` / `wabroker.py` | channels — every way in fetches, none listens |
| `vision.py` / `hearing.py` / `speech.py` / `frames.py` | reading a picture, hearing a recording, speaking, one still out of a video — ordinary READ/WRITE with a target |
| `cli.py` / `doctor.py` / `configcli.py` / `schema.py` | the subcommands: diagnose, read and change settings — the schema decides what may be written, and the allowlist and the network exceptions never are |
| `askcli.py` | `talos ask` — one turn from a script, as a channel with no special right |
| `models.py` | live model lists, cached on disk, added to the curated catalogue and never replacing it |
| `updater.py` | update beside the old tree, both suites in the new one, switch only if green |
| `eventlog.py` / `memory.py` / `usage.py` | durable log, conversation memory, metering |
| `mcpservers.py` / `skillwrite.py` | the operator-owned MCP registry, and the one gated write into the skills directory |

## Roadmap

1. `openat2()` with `RESOLVE_BENEATH` instead of realpath checks.
2. **An adapter seam for tools.** Adding a channel is already just implementing a
   protocol; adding a *tool* still touches three places, one of them inside the kernel
   (`TARGET_EXTRACTORS`). The seam should make a new effect routine without making the
   kernel optional — everything still passes the same gate, the same tokens, the same
   snapshots, the same receipts.
3. **Ownership as the boundary, not just the floor.** While the agent and its config file
   belong to the same writable user, the floor and the sandbox are code in the same
   process. A separate user for the model worker would make it a real separation. On a
   hardened installation the config already belongs to root and the agent may only read it.

Landed since this list was first written: the sandbox for `run_shell` (bubblewrap /
`sandbox-exec`, see [What it does not do](#what-it-does-not-do)), streaming replies,
timed runs under a ceiling that makes them weaker than typed ones,
[announced plans](#announced-plans) built so that planning tightens a run instead of
widening it, read-only delegation, a render-only browser, the media tools, hearing on the
machine itself, one still out of a video, keyless search, **mail as a second way in**,
a command line that grants nothing by being one, **MCP over the claude-worker seam**
(an [operator-owned registry](#the-mcp-registry) instead of a marketplace),
[WhatsApp through an operator-controlled broker](#whatsapp-through-your-own-broker), and
[skills the agent may write — but never alone](#skills-it-writes-for-itself).

## Contributing

Changes to the kernel (`policy.py`, `capability.py`, `command_floor.py`, `approval.py`,
`standing.py`, `autonomy.py`, `trust.py`, `verifier.py`, `executor.py`) need:

1. `pytest`, `redteam.py` and `e2e.py` green, in that order.
2. **Any loosening must add a red-team case** proving the boundary next to it still holds.

If you find a way past the kernel, that is the most valuable thing you can contribute —
and it belongs in the **private** channel, not in a public issue: see
[SECURITY.md](SECURITY.md), which also states the scope and the limits no patch will
remove. Everything else — a missing tool, a refusal you disagree with, a wrong answer —
is a normal issue and welcome as one.

## License

MIT. See [LICENSE](LICENSE).

Talos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README