diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 479dfb9..40e42c4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -57,6 +57,9 @@ jobs: - name: Check public hygiene run: python scripts/check-public-hygiene.py + - name: Check FAQ search metadata and links + run: python scripts/check-site-discovery.py + - name: Verify embedded signature-verifier pins run: python scripts/sync-verifier-lock.py --check diff --git a/README.md b/README.md index 73f3241..6e1f13c 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@

talos-agent.ch · Field manual · + FAQ · Changelog · Fork Talos

@@ -53,6 +54,20 @@ operation or a substitute for reviewing permissions and keeping backups. [Watch a recorded session](https://talos-agent.ch/console.html) · [Install with Pinokio](https://github.com/talos-kernel/talos-pinokio) +## Is Talos right for you? + +- **Run local models:** connect Ollama on hardware you control, or use a configured cloud provider. +- **Work from terminal or Telegram:** inspect projects, organise notes, prepare reports and run permitted tools. +- **Keep authority explicit:** approve once, grant eligible steps for the current task, or maintain exact-action standing rules. Hard denials remain denials. +- **Inspect the evidence:** review tool outcomes and the audit trail; do not mistake a confident answer for a successful action. + +Start with the [model, cost and permission FAQ](https://talos-agent.ch/faq/). +Talos is not Talos Linux or Cisco Talos. It is a self-hosted AI agent, and it remains beta. +If this approach is useful, **star the repository to bookmark it**, try a small task and +[report a reproducible result](https://github.com/talos-kernel/Talos/issues). +Want to improve it? [Fork Talos](https://github.com/talos-kernel/Talos/fork) and read +[the contribution guide](CONTRIBUTING.md). Keep private configuration and credentials out of your fork. + ``` message ──▶ event log ──▶ reason ──▶ ╔══════════╗ ──▶ capability ──▶ execute ║ KERNEL ║ token │ @@ -70,7 +85,7 @@ operation or a substitute for reviewing permissions and keeping backups. ```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 +curl -fsSL https://talos-agent.ch/install.sh | bash # then run it ``` The installer verifies the signature and the checksum, runs the full suite — and then diff --git a/scripts/check-site-discovery.py b/scripts/check-site-discovery.py new file mode 100644 index 0000000..74a61b9 --- /dev/null +++ b/scripts/check-site-discovery.py @@ -0,0 +1,110 @@ +#!/usr/bin/env python3 +"""Check the public FAQ's search metadata and crawlable paths without network access.""" +from __future__ import annotations + +import json +from html.parser import HTMLParser +from pathlib import Path +from urllib.parse import unquote, urlsplit +from xml.etree import ElementTree + +ROOT = Path(__file__).resolve().parents[1] +SITE = ROOT / "site" +ORIGIN = "https://talos-agent.ch" + + +class Page(HTMLParser): + def __init__(self, path: Path): + super().__init__(convert_charrefs=True) + self.nodes: list[tuple[str, dict]] = [] + self.ids: list[str] = [] + self.schemas: list[dict] = [] + self.schema_text: str | None = None + self.title = "" + self.in_title = False + self.feed(path.read_text(encoding="utf-8")) + + def handle_starttag(self, tag, attrs): + fields = dict(attrs) + self.nodes.append((tag, fields)) + if "id" in fields: + self.ids.append(fields["id"]) + if tag == "title": + self.in_title = True + if tag == "script" and fields.get("type") == "application/ld+json": + self.schema_text = "" + + def handle_data(self, data): + if self.in_title: + self.title += data + if self.schema_text is not None: + self.schema_text += data + + def handle_endtag(self, tag): + if tag == "title": + self.in_title = False + if tag == "script" and self.schema_text is not None: + self.schemas.append(json.loads(self.schema_text)) + self.schema_text = None + + def attrs(self, tag): + return [fields for name, fields in self.nodes if name == tag] + + +def check() -> None: + faq = Page(SITE / "faq/index.html") + assert len(faq.attrs("h1")) == 1, "FAQ must have one H1" + assert faq.attrs("html")[0].get("lang") == "en" + assert 25 <= len(faq.title) <= 65 and "Talos" in faq.title and "FAQ" in faq.title + assert len(faq.ids) == len(set(faq.ids)), "Duplicate FAQ ids" + assert len(faq.attrs("details")) >= 15, "Expected substantive question coverage" + assert len(faq.attrs("summary")) == len(faq.attrs("details")) + metadata = {item.get("name", item.get("property")): item.get("content", "") + for item in faq.attrs("meta")} + assert 80 <= len(metadata["description"]) <= 170 + assert "noindex" not in metadata.get("robots", "") + assert metadata["og:url"] == ORIGIN + "/faq/" + assert metadata["twitter:card"] == "summary_large_image" + assert metadata["og:image"].startswith(ORIGIN + "/") + canonical = [item["href"] for item in faq.attrs("link") if item.get("rel") == "canonical"] + assert canonical == [ORIGIN + "/faq/"] + graph = faq.schemas[0]["@graph"] + assert graph[0]["url"] == canonical[0] + assert graph[1]["@type"] == "BreadcrumbList" + assert graph[1]["itemListElement"][-1]["item"] == canonical[0] + assert not faq.attrs("form") and not faq.attrs("iframe"), "FAQ must stay static" + + # Resolve actual local files and fragments, not just strings that look like URLs. + for tag, fields in faq.nodes: + target = fields.get("href") if tag in ("a", "link") else fields.get("src") + if not target: + continue + url = urlsplit(target) + if url.netloc and url.netloc != "talos-agent.ch": + continue + assert not url.scheme or url.scheme == "https", target + path = url.path or "/faq/" + assert path.startswith("/"), target + local = SITE / unquote(path).lstrip("/") + if local.is_dir(): + local /= "index.html" + assert local.is_file(), f"Missing link target: {target}" + if url.fragment: + assert unquote(url.fragment) in Page(local).ids, f"Missing fragment: {target}" + + ns = {"s": "http://www.sitemaps.org/schemas/sitemap/0.9"} + locations = [node.text for node in ElementTree.parse(SITE / "sitemap.xml").findall("s:url/s:loc", ns)] + assert locations.count(ORIGIN + "/faq/") == 1 + for name in ("index.html", "docs/index.html"): + page = Page(SITE / name) + assert any(link.get("href") == "/faq/" for link in page.attrs("a")), name + assert ORIGIN + "/faq/" in (ROOT / "README.md").read_text(encoding="utf-8") + assert ORIGIN + "/faq/" in (SITE / "llms.txt").read_text(encoding="utf-8") + robots = (SITE / "robots.txt").read_text(encoding="utf-8") + assert "Sitemap: " + ORIGIN + "/sitemap.xml" in robots + assert "Disallow: /faq" not in robots + print(f"Site discovery checks passed: metadata, schema, {len(faq.attrs('details'))} FAQ entries, assets, fragments and discovery links.") + + +if __name__ == "__main__": + check() diff --git a/site/docs/index.html b/site/docs/index.html index 5816f9c..810cccc 100644 --- a/site/docs/index.html +++ b/site/docs/index.html @@ -222,7 +222,7 @@ - +
@@ -239,6 +239,8 @@

Talos AI agent: the field manual

model, and runs tools: a real shell, a confined Claude worker, a browser on request. No tool runs until a deterministic kernel has ruled on the action. The model proposes; it does not decide.

+

New here? Read the Talos FAQ: models, costs and permissions + before choosing your setup.

That one decision shapes the rest of this manual. It is why the command list is short, and why a few obvious conveniences are missing on purpose.

diff --git a/site/faq/index.html b/site/faq/index.html new file mode 100644 index 0000000..e9382f5 --- /dev/null +++ b/site/faq/index.html @@ -0,0 +1,77 @@ + + + + + +Talos AI Agent FAQ: Models, Costs & Permissions + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Talos AI agent / Frequently asked questions

+

Talos AI agent FAQ

+

A self-hosted AI agent for terminal and Telegram, with your choice of models and a deterministic permission kernel. Here is what to know before you raise the keep.

+
Read the installation guideWitness a recorded session
+
Getting startedModels & costsPermissions & privacyProject & contributions
+
+
+

Getting started

+
What is Talos AI agent?

Talos is an open-source, self-hosted AI agent that takes instructions through terminal chat or Telegram and can use tools for real work. A language model proposes each tool call; a separate deterministic kernel decides whether it is allowed, needs human approval or must be denied. Talos is an agent application, not Talos Linux or Cisco Talos. Start with the field manual or inspect the source on GitHub.

+
What can I use Talos for?

Use it to inspect a project, search and organise local notes, run permitted maintenance commands, prepare reports or delegate a bounded coding task to a configured Claude or Codex worker. The tools and host access available depend on your setup and permissions. The Command Hall shows a recorded session, not a live connection to anyone's agent.

+
How do I install Talos on macOS or Linux?

Follow the installation guide: inspect the Bash installer, install the signed release, configure your identity and model, then start terminal chat. Talos requires Python 3.11 or newer. The installer verifies the release and runs its tests; it does not start the agent automatically. A separate Pinokio launcher is also available; check the release it currently pins.

+
Can Talos run on a Raspberry Pi or a VPS?

Yes. Talos runs on Linux, including Raspberry Pi, as well as macOS. The agent and the model are separate: a Pi can run Talos while a configured provider supplies inference. Running a large model locally needs enough memory and compute for that model. Self-hosting does not imply that every model fits on a Pi. See model setup.

+
Can I use Talos as a self-hosted Telegram AI agent?

Yes. Configure your own Telegram bot and explicitly allow your identity. Talos fetches messages by long polling; the Telegram channel does not need a public webhook. Follow the Telegram setup instructions. Keep one service polling each bot token to avoid competing consumers.

+
+
+

Your models. Your costs.

+
Does Talos work with Ollama and local models?

Yes. You can configure Ollama as the model provider and run inference on hardware you control. Local inference avoids cloud-provider charges for those model calls, but hardware and electricity still cost money. Tool quality depends on the model; the permission kernel remains separate from it. Read the Ollama and model guide.

+
Can I use Claude or Codex with Talos?

Yes. Talos supports configured model providers and CLI integrations, including Claude through Claude Code, and bounded Claude and Codex coding workers. Reasoning and delegated coding are distinct roles. You must provide supported, valid access for the integration you choose; availability, usage limits and subscription eligibility are determined by that provider. Talos does not grant a model subscription or repair expired credentials by itself.

+
Is Talos free? Do I need Vercel or a Talos subscription?

Talos is MIT-licensed open-source software with no Talos subscription fee. Vercel or a paid gateway is not required. You pay for any cloud models, hosting or other services you choose; local models use your own hardware. A configured provider may have its own plan or usage charges. See the MIT licence.

+
Does /eval make every model faster?

No. /eval is a local classification and preflight diagnostic, not a faster model or a VPS inspection. It can classify a request without a model call, but that does not mean it has answered the request or executed a task. Actual response time depends on the model, context, network and required tools. A near-zero classification time is not an end-to-end speed benchmark.

+
+
+

The terms of the grant

+
Do I have to approve every action individually?

No. When offered for an attended task, Allow once approves the pending action, Allow this task covers eligible approval-required steps of that current task, and Always allow creates a standing rule for the exact action. A task approval is not a blanket grant for future tasks. Each tool call still goes through the kernel, and a hard denial cannot be turned into permission by the model. See the approval choices.

+
What does the deterministic permission kernel actually do?

It evaluates the proposed tool, arguments, derived targets and applicable policy before execution. The executor requires a capability tied to the approved call. The model cannot issue that capability itself. An audit trail records decisions and outcomes. This is an enforcement boundary, not a promise that the model never makes mistakes. Read the kernel explanation and the adversarial test documentation.

+
Does self-hosting mean my data never leaves my machine?

No, not automatically. Your selected model provider receives the context sent to it; external tools and Telegram also involve their configured services. Local inference through Ollama keeps those model calls on the host you configure, but it does not make unrelated network tools offline. Review providers, tool permissions and data flow for your deployment. Never put credentials or private runtime data in a public fork.

+
Can Talos work while I am away?

Talos supports scheduled and background work under an unattended ceiling. Actions that still need a human grant are refused or reported, rather than silently approved. Capabilities available in an attended conversation do not automatically carry over to unattended work. See the operation guide before relying on a scheduled workflow.

+
What happens if an agent or tool fails?

Inspect the recorded outcome rather than relying only on the model's summary. Talos includes stop controls, event inspection and recovery features such as undo for supported file changes. Undo is not a universal reversal of messages, remote operations or other external effects. Keep independent backups and test recovery for your own workload.

+
+
+

Judge the work

+
How should I compare Talos with IronClaw, OpenClaw or Hermes?

Compare the same task, model, host resources and permission scope. Measure completed outcomes, operator effort, latency and recovery, not just stars or test counts. Talos focuses on a readable deterministic capability kernel and scoped approvals; other projects may suit different integrations or workflows. We do not claim a universal winner. Read the documented comparison and check each project's current source for its own capabilities.

+
Is Talos production-ready?

Talos is in beta. Automated tests and signed releases are evidence for specific checks, not a guarantee of error-free operation. Review the beta operator contract, validate your own workflows and keep a rollback path. Experimental Computer adapters have separate qualification requirements; a source implementation is not a ready-to-use VM.

+
How can I star, fork or contribute to Talos?

Visit Talos on GitHub and star it if you want to keep track of the project. Fork the repository to experiment, follow the contribution guide, or open a reproducible issue. Helpful contributions include installation reports, clearer documentation and regression tests. Share only sanitised examples, never tokens, private logs or personal configuration.

+
Inspect Talos on GitHubRaise your own keep
+

These answers describe Talos, not a hosted service. Check the release notes for the version you install. A GitHub star is a bookmark and a signal of interest, not a security certificate.

+
+
+ + + diff --git a/site/index.html b/site/index.html index f1db64a..a733372 100644 --- a/site/index.html +++ b/site/index.html @@ -364,7 +364,7 @@ - +

SELF-HOSTED INTELLIGENCE. HUMAN AUTHORITY.

Room to act.
Rules to keep.

Your AI agent for real work.
Your models. Your machine. Your command.

Witness the deed ↗Raise the keep ↗

Open source · Terminal & Telegram · MIT

The model proposes. It never decides.SCROLL INTO THE HALL ↓
@@ -638,7 +638,7 @@

Measured, with the path stated

None of this asks for belief. The installer runs the unit and adversarial suites in front of you; the real-model cases are a separate opt-in E2E run.

Release snapshot: 0.20.0-beta.4. Counts describe its test suite, not speed or real-world success rates.

-
0
automated tests collected from this beta release
+
0
automated tests collected from the source tree
0
adversarial cases trying to pass the kernel
0
opt-in end-to-end cases against a real model
0
lines in the file that decides every verdict
@@ -697,11 +697,15 @@

It lives on a small always-on box, and knocks before it acts.

questions

-

Asked, answered.

+

Talos AI agent: your questions

+

Models, costs, installation and the terms of each grant. + Read the full Talos FAQ for Ollama, Claude, Codex, Raspberry Pi, + Telegram and task approvals.

What does it cost? -

Talos is MIT-licensed and free. You pay only the model provider you configure, - and the installer starts nothing until you say so.

+

Talos is MIT-licensed with no Talos subscription fee. Vercel is not required. + Model providers, hosting and local hardware may have their own costs. + Read the cost breakdown.

Which models does it run on?

Use local models through Ollama, Claude through the Claude Code CLI, or a configured API provider. The kernel judges the call, not the model. @@ -747,9 +751,10 @@

Asked, answered.

The model proposes, it does not decide. A deterministic kernel grants authority for exact arguments, once, for 30 seconds, and writes every verdict to an append-only log. Both suites run on every install, in front of you.

-
Does it need a server of mine? -

No listening socket, ever. Every channel fetches: Telegram long-polls, mail is - pulled over IMAP, WhatsApp goes through an operator-controlled broker over SSH.

+
Does Telegram need a public webhook? +

No. The Telegram channel fetches messages by long polling. You do not need + to expose a public webhook for it. Your agent still runs on the Mac, Linux + machine or server you configure. See Telegram setup questions.

@@ -794,7 +799,7 @@

The command remains yours

Codex Book of Judgement Bounds - Questions + FAQ The Watcher Command Hall Source diff --git a/site/llms.txt b/site/llms.txt index 1a87cd2..e3dfe2c 100644 --- a/site/llms.txt +++ b/site/llms.txt @@ -6,7 +6,7 @@ - Permission kernel: 985 lines of Python, the only code that decides - 33 tools, all gated; unattended runs cannot escalate -- 3219 tests (automated) and 263/263 red-team cases green at the release gate +- 3219 tests collected in the source tree; 263/263 red-team cases passed in source verification. Release contents follow their own signed tag. - MCP servers run only inside a UID-separated worker, from an operator-owned registry — no marketplace, no third-party code in the agent process - Channels: Telegram, mail (IMAP pull), CLI, WhatsApp via an operator-controlled broker — every channel fetches; no inbound port, no webhook - Updates: signed tarballs, verified before anything is unpacked; dependencies pinned and hashed, installed with --require-hashes @@ -16,6 +16,7 @@ - [Home](https://talos-agent.ch/): what it is, live policy-kernel demo in the browser - [Field manual](https://talos-agent.ch/docs/): install, identity, memory, channels, commands +- [FAQ](https://talos-agent.ch/faq/): Ollama, Claude, Codex, costs, Raspberry Pi, Telegram, task approvals and contributions - [The MCP registry](https://talos-agent.ch/registry/): extension model without a marketplace - [Honest comparison](https://talos-agent.ch/vergleich/): Talos vs. OpenClaw vs. Hermes, including what Talos does not have - [Console](https://talos-agent.ch/console.html): one real session, replayed diff --git a/site/sitemap.xml b/site/sitemap.xml index caed8aa..0fdf09b 100644 --- a/site/sitemap.xml +++ b/site/sitemap.xml @@ -7,16 +7,22 @@ https://talos-agent.ch/ - 2026-09-30 + 2026-10-07 weekly 1.0 https://talos-agent.ch/docs/ - 2026-09-30 + 2026-10-07 weekly 0.8 + + https://talos-agent.ch/faq/ + 2026-10-07 + monthly + 0.8 + https://talos-agent.ch/registry/ 2026-08-28