# Caedos

> The runtime for standing work. Caedos (said KAY-dos) is a self-hosted runtime for standing work: small programs that watch APIs, pages and feeds, and act when something changes. Your AI installs them over MCP. Quiet checks cost nothing. Nothing goes to your channels or APIs until you allow it.

The model writes the synth once. A deterministic engine runs it every time. A model is consulted only when something changed. Channels and APIs are touched only after the operator allows it.

## How a synth goes to work

1. Authoring (the author: your AI, over MCP). Writes the synth, shadows it, deploys it, reads traces, patches from evidence. Then leaves.
2. Running on Caedos (the runtime). Runs each process on its trigger, walks six phases per tick, records everything, repairs what it can.
3. Approval (the operator: the human). Allows side effects, approves or rejects queued actions, reads journals, sets policy.

Allow is a button in the operator's control room. It isn't one of the author's tools.

## Vocabulary

- synth: the program, a small declarative JSON or YAML config (synth, sources, transforms, fast_path, reasoning, actions). `agent:` is a legacy alias for `synth:`.
- process: a deployed, running synth.
- tick: one run through six phases: LOAD → OBSERVE → FILTER → REASON → ACT → SAVE. The fast path in FILTER decides whether a model is called at all.
- trace: the record of one tick: origin (what caused it), mode (live, queued, shadow), what it saw, cost, actions, config version.
- leash: approval_mode: required. Outbound actions queue for the operator's approval until they press Allow.
- shadow: one real tick with every action muted.
- Relay: signals between processes (publish_signal, signal_subscribe).
- control room: the dashboard at http://localhost:2233.

## Install

macOS or Linux, in a terminal:

    curl -fsSL https://caedos.com/install.sh | sh

Windows, in PowerShell:

    irm https://caedos.com/install.ps1 | iex

The script downloads this computer's build from https://github.com/caedos-os/caedos-run/releases, checks it against the release's SHA256SUMS, and puts caedos in ~/.local/bin (on Windows, %LOCALAPPDATA%\Programs\Caedos, added to PATH). Nothing else to install. The Windows and Linux builds can also be downloaded from the release. There is no Mac download: Apple hasn't notarized the Mac build yet, and macOS blocks it when a browser downloaded it, not when curl did.

Then open it:

    caedos start

- Control room: http://localhost:2233. CAEDOS_PORT changes the port; caedos saves it in its data folder, so the other commands find it.
- Claude Code: claude mcp add --scope user caedos -- caedos mcp
- Any MCP client: command caedos, argument mcp (stdio; it connects to the Caedos that is running). Use the full path if caedos isn't on PATH.
- If caedos mcp says Caedos isn't running, ask the person to run caedos start, or caedos service install to keep it running. Don't start it from your own shell: it would stop when your session ends.
- Keep it running: caedos service install starts Caedos when the person signs in.
- Commands: start, watch, ps, mcp, service install, service uninstall, export, import, restore, doctor, version.
- Data folder: %LOCALAPPDATA%\Caedos, ~/Library/Application Support/Caedos, or ~/.local/share/caedos (CAEDOS_DATA_DIR moves it).
- Handbook: served by your install at /api/os/docs, and delivered to MCP clients when they connect.

## MCP tools (13)

caedos_validate, caedos_shadow, caedos_deploy, caedos_run, caedos_traces, caedos_get, caedos_patch, caedos_ps, caedos_pause, caedos_kill, caedos_devices, caedos_blueprints, caedos_docs. Allow is not an MCP tool.

## Facts

- A tick that sees no change makes zero model calls, unless the synth says triggered_by: always.
- Processes whose actions touch the outside world (notify_webhook, post_to_api, mcp_action) deploy leashed.
- Every tick leaves a trace. Secrets never appear in a trace.
- Models: bring your own key for Anthropic (default), OpenAI or xAI; tiers economy, standard, premium; a daily dollar budget per process.
- State is one SQLite file on your machine. Secrets are encrypted at rest (AES-256-GCM).
- Allow isn't an MCP tool. An agent that can run commands on the computer can do anything the person can, including Allow, so leave Allow to the person.
- Sources only read: a source pointed at a write waits for Allow like an action. No synth can reach Caedos's own API.
- Listens on 127.0.0.1 by default. Single user, no authentication yet. No telemetry, no license check, no update check.
- Version 0.1.0, pre-1.0. Windows, macOS and Linux (x64 and ARM64); the Windows build isn't code-signed and the Mac build isn't notarized yet, so both are beta.
- Closed source. License: Elastic License 2.0, free for personal use and for work; you may not offer Caedos to others as a hosted or managed service.

## Pages

- [Home](https://caedos.com/): what Caedos is
- [How it works](https://caedos.com/how-it-works): how a synth goes to work, the tick, the authoring loop, the leash, traces, the Relay, failure
- [Product](https://caedos.com/product): capabilities, the 27-primitive catalog, and what it doesn't do yet
- [Start](https://caedos.com/start): install, open, and connect your AI over MCP
- [Security](https://caedos.com/security): what is protected, how, and what isn't yet
- [Pricing](https://caedos.com/pricing): free on your machine, Caedos Cloud later, license and model costs
- [Changelog](https://caedos.com/changelog)
- [Status](https://caedos.com/status): version, supported runtime, known limitations
- [Docs](https://caedos.com/docs)

## Blueprints

- [Price watcher](https://caedos.com/blueprints/price-watcher): No model calls. Pure change detection.
- [API health sentinel](https://caedos.com/blueprints/api-health-sentinel): No model calls. Alerts on change, both directions.
- [GitHub release watcher](https://caedos.com/blueprints/github-release-watcher): No model calls. No GitHub token for public repos.
- [HN keyword watcher](https://caedos.com/blueprints/hn-keyword-watcher): No model calls. Free HN search API.
- [Page change watcher](https://caedos.com/blueprints/page-change-watcher): Model only when the page changed · standard tier · ≤ $0.05/day.
- [Daily HN brief](https://caedos.com/blueprints/daily-brief): One economy-tier call a day · ≤ $0.01/day.
- [Keyword pulse analyst](https://caedos.com/blueprints/keyword-pulse): Model only when mentions shift · economy tier · ≤ $0.02/day · publishes team.findings.
- [Relay bridge](https://caedos.com/blueprints/relay-bridge): No model calls. No outside world. team.findings → team.digest.
- [Outbound courier (via your n8n)](https://caedos.com/blueprints/n8n-courier): No model calls. Leashed by default. Wakes on content.draft.

## Use cases

- [The release you'd have missed](https://caedos.com/use-cases/release-watch)
- [The outage you hear about once](https://caedos.com/use-cases/outage-once)
- [The competitor page, read for you](https://caedos.com/use-cases/competitor-page)
- [The draft that waits for your tap](https://caedos.com/use-cases/draft-waits)